Micro Focus Enterprise Server 2.3 Update 1 for Windows

Welcome to Enterprise Server

  • Welcome
  • Product Information
  • Managing Licenses

What's New

  • New Features in Enterprise Server

Featured Sections

  • Deploying COBOL Applications
  • Enterprise Server
  • Mainframe Support for Deployed Applications
  • Running an Application from the Command Line
  • Tools
  • PL/I Programming

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

Note: Check the Product Documentation section of the Micro Focus SupportLine Web site and the Micro Focus Infocenter for any updates to the documentation which might have been uploaded.

Enterprise Server provides the execution environment for applications created with any IDE variant of Enterprise Developer.

  • The Micro Focus Community
  • New Features
  • Significant Changes in Behavior or Usage in This Release
  • Product Information
  • Managing Licenses
  • Help on Help
Parent topic: Micro Focus Enterprise Server 2.3 Update 1 for Windows


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 Enterprise Server
  • Features Added in Enterprise Server 2.3
  • Features Added in Enterprise Server 2.2 Update 2
  • Features Added in Enterprise Server 2.2 Update 1
  • Features Added in Enterprise Server 2.2
  • Features Added in Enterprise Server 2.1 Update 1
  • Features Added in Enterprise Server 2.1
  • Features Added in Enterprise Server 2.0
Parent topic: Welcome


New Features in Enterprise Server

This release provides enhancements in the following areas:

  • Application Server JCA support for Enterprise Server
  • Enterprise Server
  • Data File Tools
  • Database Access - HCO for SQL Server
  • Database Access - Mainframe Batch Database Tools (MBDTs)
  • Database Access - OpenESQL
  • File Handling
  • iFileshare - Fileshare under Enterprise Server (Early Adopter Product)
  • PL/I support

Application Server JCA support for Enterprise Server

Back to Top

This release provides support for:

  • Automatic connection recovery to an active Java application server when an enterprise server region is restarted. This applies to:
    • COBOL resource adapters
    • CICS resource adapters
    • All CICS API based programs
  • The IBM implementation of CICS resource adapter for WebSphere 8.5 and JBoss 7.1.1.

Data File Tools

Back to Top

This release provides improved security and increased support for more file types. Features include:

  • Certain aspects of Enterprise Server security are honored when you attempt to access data sets. If the Enterprise Server region has security enabled, logon details must be authenticated before you can access the data set. If the details are unable to be authenticated, access is denied.
  • When using a record layout, certain data is now validated at field level (to ensure the contents is compatible with its picture string ) and record level (to ensure the record length matches the layout size).
  • Full editing support has been added for variable block sequential files and relative files. Full editing is also available for line sequential files, as long as they do not contain any binary data.

For more information see Related Information at the end of this topic.

Database Access - HCO for SQL Server

Back to Top

This release provides the following new features:
  • End-to-end demonstrations that show several methods for submitting a JCL batch job that calls COBOL stored procedures. To view these demos, see the SQL demonstrations in the Mainframe Samples browser.
  • The SPCALLLOCAL SQL compiler directive option, used to convert an EXEC SQL CALL into a call to a local COBOL subroutine instead of a call to a SQL Server SQLCLR stored procedure.
  • Extended support for conversion of the DB2 CONCAT function.

Database Access - Mainframe Batch Database Tools (MBDTs)

Back to Top

Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability; however, this feature is not intended for production use and it is not supported as such.

This release provides MBDTs support for DB2 LUW partitioned tables.

For more information see Related Information at the end of this topic.

Database Access - OpenESQL

Back to Top

This release provides the following new features:

  • Support for the Oracle fully managed ODP.NET driver.

Enterprise Server

Back to Top

This release provides support for the SO_RCVTIMEO and SO_SNDTIMEO timeout options of EZASOKET support that help reduce the risk of applications becoming unresponsive due to EZASOKET APIs not completing.

File Handling

Back to Top

The following enhancements have been made to file handling processes:
  • A new indexed file format, IDXFORMAT12, has been introduced to improve file maintenance and recovery procedures when using the rebuild utility. This file format is similar in structure and use to IDXFORMAT8. Where the two formats differ is that an IDXFORMAT12 file has an accompanying side file (.idx file) containing the indexed key information.

    You can use this type of file with the new rebuild /q option. This rebuild process is considerably quicker than other rebuild processes such as a data scrape or rebuild /p.

  • Faster SORT operations for fixed block records - when using the DFSORT emulation, the performance when sorting fixed block records has greatly improved.

iFileshare - Fileshare support under Enterprise Server (Early Adopter Product)

Back to Top

Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.

You can configure iFileshare to offer enhanced availability for mission critical files by configuring a high availability group, consisting of a primary iFileshare server and a number of stand-by servers.

Files that are critical to your application can be replicated from a primary server onto the stand-by servers. Should the primary server fail, you have up-to-date data (minus any in-flight transactions) available.

If Enterprise Server work is being hosted on the primary region within the group, the setup must be consistent on all standby Fileshare hosting regions so that work can continue in the event of a failover.

For more information see Related Information at the end of this topic.

For more information see Related Information at the end of this topic.

Mainframe support and emulation

Back to Top

This release provides the following enhancements:
  • Support for using multiple catalog files (up to 32).
  • Support for storing the spool files in a location that differs from the location of the catalog file.
  • Enhanced support for searching the catalog using wildcards.

PL/I support

Back to Top

Support is available for the following features:

  • FIXED BIN(63) data type - PL/I programs that utilize FIXED BIN data types that are larger than FIXED BIN(31) are now supported which enables you to migrate such programs more easily to distributed platforms.
  • TRIM() built-in functions - the Open PL/I macro preprocessor now supports the TRIM() built-in function.
  • A 64-bit Open PL/I peephole optimizer - when compiling 64-bit Open PL/I programs optimization for speed, a peephole optimizer is now run against the intermediate code to improve your applications' performance. Any code which has attributes that benefit from peephole optimizations will then run faster.

For more information see Related Information at the end of this topic.

For more information see Related Information at the end of this topic.

Parent topic: New Features
Related information
Data File Tools
IFileshare


Features Added in Enterprise Server 2.3

This release provides enhancements in the following areas:

  • Database access
  • Environment variables
  • File handling
  • iFileshare - Fileshare support under Enterprise Server (Technology Preview)
  • Mainframe compatibility
  • Micro Focus Infocenter
  • Spooler housekeeping
  • Transaction class (TRANCLASS) support

Database access

Back to list

This release provides the following enhancements to database access:

HCO for DB2 LUW
This release provides:
  • GUI versions of data migration tooling
  • A new tool that enables you to bind or rebind all packages. See BindAll Packages Tool for details.
  • 64-bit support for PL/I on appropriate platforms. See Additional Software Requirements on Windows for details.
HCO for SQL Server
This release provides:
  • Context Help is now provided for:
    • Options for HCO for SQL Server tools
    • Each tool in the HCO for SQL Server user interface
OpenESQL
ADO.NET Connection Editor
In this release:
  • The ADO.NET Connection Editor has been redesigned using a series of Wizards that guide you through the processes of adding, copying, and removing connections.
  • Context Help is now provided for the main window, and each Wizard page and dialog box.
Date/Time Processing
This release provides streamlined datetime processing for ODBC, ADO.NET, and JDBC.
PL/I
This version provides 64-bit support for PL/I on appropriate platforms. See Additional Software Requirements on Windows for details.
PostgreSQL
In this release, PostgreSQL 9.4 has been tested with OpenESQL and OpenESQL Assistant using the following PostgreSQL software:
Server software
PostgreSQL EnterpriseDB version 9.4.4
Client software
  • psqlODBC driver version 09.03.04.00
  • JDBC41 PostgreSQL driver version 9.4-1201
  • Npgsql ADO.NET 4.0 driver version 2.2.5
PostgreSQL 9.4 has been tested with OpenESQL and OpenESQL Assistant on the following Windows platforms:
  • Windows 32-bit
  • Windows 64-bit
Note: Micro Focus provides compatibility for PostgreSQL but does not directly contribute to or support the PostgreSQL open source project. Any issues relating to PostgreSQL functionality should be addressed through an open source support vendor.
Mainframe Batch Database Tools (Technology Preview)
This release includes mainframe batch database tools (MBDT) that provide the following functionality for Oracle, DB2 LUW, and SQL Server agnostically, as well as specifically for HCO for SQL Server:
  • DSNTEP2
  • DSNUTILB LOAD
  • DSNUTILB UNLOAD
  • 32-bit and 64-bit support
  • New batch configuration utility
XA Switch Modules
In this release, the XA interface has been redesigned to provide:
  • Consistent look and feel for SQL Server, DB2, and Oracle user personalization
  • Consistent look and feel for both RM dynamic and static registration (SQL Server, DB2, Oracle, generic one-phase commit for ODBC)
  • Additional support for two instances of the same switch module using Web Services applications via the new XAID compiler directive
  • Using a specified XA resource only with batch applications executing under Enterprise Server

For more information see Related Information at the end of this topic.

Environment variables

Back to list

The following new environment variables are available:

MFJ_REPRO_EMPTY
Enables or disables the ability for the IDCAMS REPRO action to copy from a pristine VSAM file. Permissible values: Y or N.
ES_JESYSMSG_RESTRICTED
When system message spool files are being routed directly to the Output queue, by using ES_JESYSMSG_OUTPUT, you can hold back spool files based on their class, by using ES_JESYSMSG_RESTRICTED. Permissible values: class names or numbers entered as a continuous string; for example, ES_JESYSMSG_RESTRICTED=ABC123.

For more information see Related Information at the end of this topic.

File handling

Back to list

This release contains the following new configuration options:

ACUFH
Enables or disables the use of the ACU file handler (ACUFH), which is required to handle Vision and RM/COBOL indexed files.
ESACUFH
Enables or disables the use of the ACU file handler (ACUFH) for file handling operations running under Enterprise Server. ACUFH must also be enabled for this option to take effect.

For more information see Related Information at the end of this topic.

iFileshare - Fileshare support under Enterprise Server (Technology Preview)

Back to list

Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability; however, this feature is not intended for production use and it is not supported as such. Furthermore, Micro Focus does not guarantee that this feature will be delivered at a GA level and if it is, then the functionality provided might differ considerably from this technology preview.

Should you wish to test and provide feedback for this feature please contact Micro Focus Support Line for instructions on how to enable the new functionality.

You can configure iFileshare to offer enhanced availability for mission critical files by configuring a high availability group, consisting of a primary iFileshare server and a number of stand-by servers. (Currently, this type of configuration only supports having one stand-by server)

Files that are critical to your application can be replicated from a primary server onto the stand-by servers. Should the primary server fail, you have up-to-date data (minus any in-flight transactions) available.

To reduce the complexity and to increase the stability of an iFileshare high availability group, it is recommended that each region is configured as a dedicated iFileshare server. If other Enterprise Server work is hosted within the group, the setup must be consistent on each server so that in the event of a fail-over, the non-Fileshare work can be continued on the new primary server.

For more information see Related Information at the end of this topic.

Mainframe compatibility

Back to list

  • IMS DBCS - Enterprise Server IMS support has been expanded to include applications that use double-byte character sets (DBCS). MFS EATTR=ECGS (full DBCS string without SOSI) is now supported.
  • Implement /DIS USER DEQUEUE - the /DEQUEUE USER command is now available to remove messages from the message queue to provide you with greater flexibility when managing IMS systems.

For more information see Related Information at the end of this topic.

Micro Focus Infocenter

Back to list

The Micro Focus Infocenter Web site (http://documentation.microfocus.com) has been upgraded and now includes the following improvements:

  • Scope being persisted when you select a product documentation in the Product Documentation section on the Micro Focus SupportLine Web site and choose to view the documentation in the Micro Focus Infocenter.
  • Updated Scope settings - provides the ability to nest four levels deep when setting a scope.
  • Scope being persisted between browser sessions once it has been set.
  • Creating automatic scopes using the Search Topics icon, Search Topics.
  • A link to change the scope from the search results when there are too many results.
  • Improved Boolean search expressions.
  • Details included with the search results.
  • Help on how to use the Infocenter and how to construct search expressions - available using the Infocenter Help button, Infocenter Help.

For more information see Related Information at the end of this topic.

Spooler housekeeping

Back to list

A new spooler housekeeping utility has been introduced (MVSSPLHK). It offers additional archiving functionality compared to the previous spooler housekeeping utility (MVSP0027), and can also be configured to run directly from a JCL job.

For more information see Related Information at the end of this topic.

Transaction class (TRANCLASS) support

Back to list

Transaction class (TRANCLASS) support is no longer a technology preview feature, and is now a full release feature.

For more information see Related Information at the end of this topic.

Parent topic: New Features
Related reference
File Handler Configuration Options
iFileshare ESMAC page
Micro Focus FTP Utility MFFTP
Spooler Housekeeping


Features Added in Enterprise Server 2.2 Update 2

This release provides enhancements in the following areas:

Character Set Enhancements

The following character sets, available using the MFCODESET environment variable, have been enhanced or added in this release:

  • Thai Extended (0066) - new
  • Korean (0082)
  • Simplified Chinese (0086)
  • Traditional Chinese (0886)

There are also a number of double-byte character sets that are now capable of mixed single-byte and double-byte character conversion; see the definition of MFCODESET in Environment Variables in Alphabetical Order for more information.

Database Access

The following new features are available in database access support:

COBSQL
HCO for DB2 LUW
This release introduces GEN-HV-FROM-GROUP - a new DB2 ECM compiler directive option, that generates host variables for all elementary data items when a multiple-level group variable is used in a FETCH or singleton SELECT DB2 statement.
HCO for SQL Server (HCOSS)
This release provides the following new HCOSS features:
  • DATE/TIME formatting - the OpenESQL Configuration Utility now supports DATE/TIME formatting for HCOSS batch utilities.
  • Multi-row INSERT - supports a multi-row INSERT statement.
OpenESQL
This version provides the following new OpenESQL features:
  • Support for SQL Server 2014.
  • New SQL Compiler directive options:
    • DETECTDATE=SERVER - resolves host variables alignment with column data types in an SQL table.
    • GEN-HV-FROM-GROUP - generates host variables for all elementary data items when a multiple-level group variable is used in a FETCH or singleton SELECT SQL statement.
  • Sample applications - the following native COBOL SQL sample applications are new with this version:
    • Get Diagnostics - demonstrates how to use GET DIAGNOSTICS EXEC SQL calls to get diagnostic information from various DBMSs.
    • LOB Data Types - Demonstrates how to INSERT and SELECT LOB data in a native application using various DBMSs.
XA switch modules
The following XA switch module updates are available in this version:
  • Oracle switch module:
    • Supports User Impersonation when statically registered.
    • Enables you to specify which XA resource definitions use User Impersonation.
    • Now compiled with one source file, rather than two.
  • SQL Server switch module:
    • Enables you to specify which XA resource definitions use User Impersonation.
    • Now compiled with one source file, rather than two.

External Call Interface (ECI)

Enhancements to the ECI include:

  • The ECI for Java clients is no longer restricted to the 32K Commarea. You can now transfer virtually unlimited containers of any size in a channel to a CICS server program. See ECI Java Interface for more information.
  • Java support for IBM's implementation of ECI, which, in turn, uses the Micro Focus implementation.
  • A ECI RA for WebSphere; however, in this release, no IMTK tooling is provided for servlets or JSP.

External Security Facility (ESF)

The Enterprise Server External Security Facility (ESF) now supports caching the results of some security queries. This can improve the performance of enterprise server instances and of the MFDS when they are configured to use external security.

To enable caching, you need to set non-zero values for the Cache limit (maximum size of the cache) and Cache TTL (Time To Live, or how long before a cached result expires) settings on the MFDS Security tab, the Default ES Security tab, or on the Security tab for an individual enterprise server. (Currently, the cache settings for Security Managers have no effect; you need to set cache parameters on one of the three Security pages mentioned earlier.)

For more information, see http://supportline.microfocus.com/examplesandutilities/doxygen/caching.html.

IMS Connect

This release now supports Java IMS Connect messages except when also using the IBM-supplied HWSJAVA0 I/O exit, excluding customizations to that exit.

PL/I General Enhancements

Enhancements are provided in the following areas:

  • Attributes - the PL/I DECLARE statement now supports the OPTIONAL attribute as part of the parameter-descriptor list or as an attribute in a parameter declaration. This provides an improved functionality and a greater language compatibility for customers looking to migrate applications from z/OS environments.
  • Built-in functions - the PL/I Compiler and run-time system now support the PRESENT and OMITTED built-in functions which provides an improved functionality and a greater language compatibility if you are looking to migrate applications from z/OS environments.
  • Compound operators - the PL/I macro preprocessor now supports the compound operators += , -=, *=, and /= within macro assignment statements.
  • Error handling - you can now use the EXEC CICS HANDLE ABEND check which provides a consistent error handling technique for PL/I programs running under CICS that is consistent with error handling on the mainframe. EXEC CICS HANDLE ABEND determines error handling for programs running under CICS. Conditions detected by CICS cause an abend if established using EXEC CICS HANDLE ABEND, and PL/I ON units do not get control. If EXEC CICS HANDLE ABEND is not established, CICS defines that the action taken will be as defined by CICS, which normally leads to a transaction abend.

Transaction classes (Technology Preview)

Transaction classes provide a mechanism to limit the number of CICS® tasks in your system. By spreading your tasks across a number of transaction classes and configuring the maximum number of tasks that can be dispatched within each transaction class, you can control resource contention between tasks and limit the number of tasks that CICS considers eligible for dispatching at task attach.

Tunables

This release includes the following new tunable:

  • reduce_java_signals - specifies the options that are passed to a JVM when mixing Java and COBOL.
Parent topic: New Features
Related reference
Alphabetical list of environment variables


Features Added in Enterprise Server 2.2 Update 1

This release provides enhancements in the following areas:

Micro Focus Heartbleed Update

This product includes OpenSSL version 1.0.1p.

Btrieve Support

Support for the Btrieve file handling system from Pervasive Software Inc. has been added into Enterprise Developer.

Support is restricted to native COBOL, in a Windows environment.

Compare and Synchronization Monitor

With the release of Enterprise Developer 2.2 Update 1, the Compare and Synchronization Monitor has been updated to version 2.

Version 2 is greatly improved in terms of performance, especially during initial checkout of partitioned data sets or when synchronizing a large number of members. Also, the user interface has been improved, and some of the functions available in the old version have now changed or become obsolete.

Compiler Directives

The following Compiler directives have been added in this release:
ILPARAMS
Determines the way in which you call a method that contains an array as its last receiving parameter.
INIT-BY-TYPE
Initializes Working-Storage Section data items to a default value, according to their type.
  • Alphabetic, alphanumeric, alphanumeric edited, and numeric edited items are initialized to spaces.
  • Numeric items are initialized to zero.
  • Pointer items are initialized to null.
  • Index items are initialized to the value 1.

Enterprise Server Integration in the IDE

You can now use the context menu for the servers in Server Explorer to enable the display of the Enterprise Server log information in .

Enterprise Server MQ-IMS Bridge

Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.

This release provides support that enables WebSphere MQ applications to communicate with IMS applications in an Enterprise Server region.

Environment Variables

The following environment variable has been added in this release:
strictvsam
strictvsam enables strict mainframe emulation when processing VSAM files.
When set to ON and running under mainframe emulation, file status 37 is returned for an existing VSAM file when opened for OUTPUT if the file has data or previously had data written to it, or if the file is of a different format to the file on disk. When set to OFF, file status 0 is returned and a new file is created when an existing VSAM file is opened for OUTPUT. This variable is set to OFF by default.

Fileshare Recovery

Recovery of Fileshare data files has been enhanced.

Rollback recovery is a faster process that aims to fix the files from their failed state.

This process cannot be used in all scenarios, but a new user exit has also been introduced that allows you to programmatically control which files you wish to recover with this process.

Hot backups are also a new introduction, which allow you to perform a backup without having to shut down Fileshare.

HCO for DB2 LUW

  • Support added for DB2 LUW version 10.5
  • Enhanced RETURN-CODE processing
  • The HCO DDL processor now accepts column names with a length greater than 18 characters.
  • The HCO Import Data tool now processes CLOB data less than 32K in size.
  • The HCO Import Data tool can now convert DSNTIAUL import files to delimited format, enabling the actual import to be done by DB2 LUW IMPORT and LOAD utilities. This is done using the new SAVEDEL and CHARDEL parameters.

HCO for SQL Server (HCOSS)

  • Support for the mainframe SET CURRENT SQLID statement.
  • Support for the mainframe LEFT and RIGHT scalar functions.
  • Data Migration tools now support the mainframe ALIAS and SYNONYM objects.

Mainframe Emulation

Previously, MGMTCLAS was supported by simply saving it on the catalog record when a dataset was allocated in JCL using the MGMTCLAS parameter on the DD statement. Starting with this release, you can use batch jobs to define MGMT classes and to specify the EXPIRE AFTER time (in days).

Mainframe Subsystem

Casspool performance enhancement
As part of an enhancement to improve performance when browsing the spool queue of an Enterprise Server, you must update the casspool file for any Enterprise Server created before Enterprise Developer 2.2 Update 1 before you can submit jobs to it.
To update the casspool for each Enterprise Server, from a command prompt, run fixcasspool.bat, located in %COBDIR%\bin and %COBDIR%\bin64, using the following syntax:
fixcasspool.bat casspool.dat backup.dat
Where:
casspool.dat
The spool file, located in the same directory as the Enterprise Server's system catalog, that will be updated.
backup.dat
A file that will be created with a backup of the old casspool.dat file. If backup.dat already exists, the update is not run.

If you do not update casspool and attempt to start Enterprise Server, the following messages are displayed in the console:

JES000011E Batch Spool File Error; Status [39]

JES000130E Note JES000011 Error - New casspool indexes may need generating. See error description in product docs

Managed COBOL Syntax

This release includes the following enhancements to the managed COBOL syntax:

Specifying parameters in the method signature
You can now specify passing parameters and returning items in the method signature, instead of using a Procedure Division header. This applies to methods, indexers, iterators, constructors and delegates.
CONSTANT keyword
Use the CONSTANT keyword on a field to protect it from being altered.
Operations on string fields
You can now use the STRING, UNSTRING and INSPECT statements on fields of type string.

PL/I

PL/I support within the IDE now includes the following enhancements:

  • Support for new built-in functions

    The PL/I Compiler and Runtime now support the following new built-in functions:

    • DAYS
    • DAYSTODATE
    • SECSTODATE
    • SECS
    • WEEKDAY
    • DAYSTOSECS
    • ONSUBCODE
    • REPATTERN
    • IAND
    • IOR
    • INOT
    • OMITTED
    • XMLCHAR

    This provides an improved functionality and a greater language compatibility when you migrate applications from a z/OS environment.

  • Support for %OPTION in the PL/I macro preprocessor

    You no longer need to modify application code that uses %OPTION in order for it to compile successfully.

  • Support for QUOTE() and COMMENT() built in functions.

    This enables the use of PL/I macros that generate code using these built-in functions.

  • Support for IBM Style %INCLUDE(s) that utilize PDS name as part of include file names.
    The PL/I macro preprocessor now parses the %INCLUDE syntax of the form shown below and utilizes the –isuffix and –ipath Compiler directives to locate the “member”.
    %INCLUDE MYPDS(MYMEMBER);
    This provides an improved language compatibility with the application code without the need to modify the original underlying source code.
  • Support for PL/I AREA data items up to 2Gb.

    Open PL/I now supports the declaration and usage of variables of type AREA up to 2Gb in size. This provides you with improved functionality and greater language compatibility when migrating applications from a z/OS environment as there is no need to modify the code in order to deal with a maximum area size of 32Kb.

  • Enhanced compatibility with the DISPLAY() REPLY() syntax.

    The PL/I Compiler and runtime now provide a DISPLAY() REPLY() syntax that is no longer dependent upon the use of the SYSIN and SYSOUT DD’s and that no longer causes behavioral differences if stream IO to SYSIN/SYSOUT is intermingled with programs using DISPLAY() REPLY().

  • Support for big-endian style bit strings on little-endian platforms.

    Using a new Compiler directive –bitsltr to compile programs that have logic that is dependent on big-endian bitstring ordering enables you to utilize the code unchanged on Open PL/I little-endian platforms (such as Windows, Red Hat Linux, SUSE Linux). This enables you to migrate applications that make an assumption about bit ordering on the underlying operating system or hardware and to run them unchanged.

  • Support for the –initcall Compiler directive.

    Compiling a PL/I program with the –initcall directive causes the specified program to be invoked prior to any user logic. This enables you to customize your environments and do things such as tracking which routines have been invoked, detect memory corruption prior to routine startup, establish database connectivity.

  • Support for the “F” option in PLIDUMP.

    A PLIDUMP which was generated using the “F” option will now attempt to list all known information about files which have been accessed during the execution of the program and includes information about the last IO operation, key values, and a dump of buffers, if available. This enables you to identify more easily the cause of file-related failures and what file operations were in progress at the time of failure.

  • Alternative Index Performance Improvements for the CASSPOOL command.
  • Support of the SHAREOPTIONS property in a VSAM cluster.

Run-time Launch Configuration Files

Use a run-time launch configuration file to ensure an application can be launched when it is deployed in a separate location to the run-time system (in the case of dynamically bound applications), or when the licensing daemon is not already running.

XA Switch Modules

This release provides the following new functionality:

  • New two-phase commit module for SQL Server based on Microsoft's XA switch. This provides support for xa_recover.
  • Support for DB2 LUW version 10.5.
  • Support for Oracle version 12.1.
Parent topic: New Features


Features Added in Enterprise Server 2.2

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.

Emitters

A new emitter, JAVALOGGER, is available for JVM COBOL.

Emitter properties and variables

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

File Handling

New features include:

  • The DATEDIFF function as part of the DFSORT emulation. There are some limitations of its use.

HCO for SQL Server (HCOSS)

Several updates have been made to the HCOSS tool set:
DB2 database batch migration
This set of batch utilities provides an alternative to the standard HCOSS database migration tools.
Note: This feature is in early adopter release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.
Schema Extract tool
This tool now provides:
  • Updated security that enables users to study extracted schemas without accessing the catalog
  • Extracted schema modification
  • Export and import capabilities
Application Assessment tool
This tool now enables you to perform data analysis on schema extract files and identify structures that are not supported by SQL Server, or that could require manual modification before HCOSS can accurately transfer the data to SQL Server.
OPTION SQL compiler directive option
New parameters have been added to handle additional host variable types.

IMS

Database recovery
IMS database recovery using the new IMS Database Forward Recovery and Backward Recovery features is available. These consist of a set of backup and restore utilities that enable you to restore your IMS database complete with the most recent updates.
Locking improvements
Internal Resource Lock Manager (IRLM) support has been added to provide more granular locking capabilities, allowing for increased sharing and decreased contention and deadlock risk.

Mainframe Subsystem Support

JCL System Catalog
You can now use in-stream data for DDs within JCL procedures. This change is to maintain compatibility with mainframe JCL processing which recently introduced the same change.
JCL Public Catalog API
You can now access and update JES Catalog information.
CICS External Call Interface (ECI)
Micro Focus proprietary support for the CICS External Call Interface (ECI) has been enhanced. ECI uses the Micro Focus BINP protocol, thus eliminating the need for third-party middleware. Additional features include support for extended LUW (logical unit of work) and new support for Java clients. For more information, see IBM External Call Interface (ECI) and External Presentation Interface (EPI).

Managed COBOL

Named and optional parameters
Two new types of parameter have been introduced for use during method invocation:
Named parameters
As part of the invocation expression, you can define a value for a parameter named in the method definition. The named argument must be specified after any positional arguments, and must not correspond to any of those preceding arguments.
Optional parameters
Optional parameters are parameters defined with a default value in the procedure division header of the invoked method. If none of the arguments passed in during invocation correspond to this parameter, the default value is used in the method; if an argument does correspond, the value that was passed in is used.
Delegates and events

A number of new features have been added that relate to delegates and events:

Note: Some of these features were also available in previous versions of Enterprise Developer.
The ATTACH and DETACH statements
Use these statements to attach or detach a delegate, method group or an anonymous method to or from an event.
The RUN statement
Use this statement to invoke a delegate once it has been created.
Combining delegates
Use the '+' operator to add a method group, anonymous method or another delegate to a delegate, and use the '-' operator to remove a method or another delegate from a delegate.
Method groups conversions
Use the METHOD keyword to specify a compatible method from a method group, and convert it to a delegate.

PL/I support

  • EBCDIC support
  • Support for XML (using XMLCHAR, PLISAXA, PLISAXB, and PLISAXC)
  • Preprocessor support for programs written using EXEC DLI
  • Support for PL/I programs running WebSphere MQ
  • Support for Open PL/I programs running as DB2 stored procedures

SQL

EXEC ADO LOAD DATATABLE Statement
Enables you to populate DataTables using both static and dynamic queries.
EXEC SQL GET DIAGNOSTICS Statement
Enables you to get diagnostic information for the last OpenESQL statement executed.
OPTION compiler directive option
New parameters have been added to handle additional host variable types, and to set the DATE SQL compiler directive option to EXTERNAL for .NET applications.
XA switch modules
This release includes support for XA switch modules that enable CICS- and JES-initiated transactions to run under Microsoft SQL Server using different user credentials than those specified within the XA open string.
Parent topic: New Features


Features Added in Enterprise Server 2.1 Update 1

Enterprise Server

The following new features and enhancements are available:

Clustering
Enterprise Server Clustering allows the scaling-out of work units, so that an increased number of operating system images can share the workload, resulting in high-performance, multi-system data sharing across all platforms.
Historical Statistics Facility
The Historical Statistics Facility has been extended to include the generation of JCL file records, increasing the amount of information customers have available to assist them in monitoring and tuning their Enterprise Server installations.
Recovery of in-doubt XA transactions
Some events in XA environments can result in ‘in-doubt’ transactions, where all parts of a composite transaction are not committed through all participating resource managers. The recovery of such in-doubt transactions is now supported.
SSL Support for the CICS Web Interface
Enterprise Server now allows clients and servers to identify themselves through X.509 certificates and participate in SSL-enabled conversations.

HCO for DB2 LUW

  • Support for 64-bit DB2 ECM
  • Support for 64-bit compile and runtime
  • Support for DB2 10.1
  • New DB2 SQL compiler directive option, BGP, to enable background parsing.

HCO for SQL Server

  • Data Transfer tool enables you to:
    • Specify the number of error rows to identify before committing them to the log file.
    • Transfer tables in one SSIS package instead of one package per table (optional).
    • Execute DDL for tables
    • Transfer DDL
  • The Generate DDL tool provides you the option of using SQL Server database collation or preserving mainframe DB2 collation with SQL Server.
  • Migration of DB2 temporary tables has been enhanced.

PL/I Support

  • Support for executing PL/I programs using IBM WebSphere MQ software
  • DEFINE ALIAS support for the Open PL/I Compiler for XML
  • Support for TSO/IDCAMS
  • Improved file I/O speed when using the PL/I language to read or write sequential, indexed and relative record files
  • To enable PL/I for CICS, JCL, IMS you only need to set ES_PLI_SUPPORT=Y. You no longer need to set ES_PL1_MFFH_JCL=Y.
  • Support for character picture data types A,X
  • Support for %XINCLUDE (macro preprocessor and compiler)
  • Support for %OPTION (macro preprocessor)
  • Tolerance for source code containing INLINE and ABNORMAL attributes.
  • Support for the TINY and HUGE built-in functions
  • New PLICTF and PLICTFHX built-in functions
  • Support for the PARAMETER attribute
  • Support for the NONINIT attribute
Parent topic: New Features


Features Added in Enterprise Server 2.1

Enhancements

Building to .int, .gnt, and .lbr files

All sources for native COBOL and mainframe subsystem projects can be built to either .int or .gnt files. Native COBOL projects can optionally be bundled into an .lbr file.

Enterprise Server

  • CICS External Call Interface (ECI) - Micro Focus proprietary support for ECI is now available. ECI uses the Micro Focus BINP protocol and negates the need for third-party middleware. For more information about ECI support, read the section IBM External Call Interface (ECI) in your product help.
  • Enterprise Server Batch Clustering is now available as a technology preview. Features include:
    • Support for sharing of both the catalog and spool between multiple batch regions is included as a technology preview.
    • Allows multiple batch regions to share commonly configured resources by providing global locking facilities to manage contention.

    For further details about this feature, contact your Micro Focus technical account management team.

  • Micro Focus Batch Scheduler Integration solution - enables you to submit, execute, and feedback between Enterprise Server and a scheduler that controls JCL job execution.
  • Support for running TSO commands in a TSO batch session using the IDAEFT01 (IKJEFF01) utility is now available.
  • The mfds –x export command line option has been extended to support repository export to an XML-format file. The syntax is as follows:
    mfds -x [repository type] [repository address] [server name] <opts> <user id> <password>

    Where:

    [repository type]
    • 1 = file:///
    • 5 = XML
    [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> and <password>
    the MFDS credentials required if administration access is restricted
  • The new –g option is used to allow XML format repository import. The syntax is as follows:
    mfds -g [repository type] [repository address] <opts> <user id> <password>
    [repository type]
    5 = XML
    <opts>
    Not currently in use.
  • XML repository import - extends the MFDS repository export to XML and import from XML introduced in Enterprise Developer 2.0 to UNIX platforms. This allows administrators to export, modify and then reimport Enterprise Server instance configuration data in XML format.

Mainframe Access

MFA Server
MFA Server has been updated to version 4.00 (BASE), and provides the following enhancements:
  • Double-byte character support using the following code pages:
    • Traditional Chinese with Taiwanese additions (BIG5)
    • Korean (KSC5601)
    • Simplified Chinese (SCHINESE)
    • Japanese - Kanji (SJISKANJI)
    • Traditional Chinese (TCHINESE)
  • Additional qualifiers for use with the new code pages:
    default
    EBCIDIC SI/SO added on upload, removed on download
    -SOSI-K
    EBCIDIC SI/SO assumed on upload, preserved on download
    -SOSI-A
    ASCII SI/SO assumed on upload, preserved on download
    -SOSI-S
    Spaces converted to SI/SO on upload. SI/SO converted to spaces on download
    Note: This will only work correctly with text that originates on a host.

HCO for SQL Server

HCOSS now supports rowset cursors.

IMS support

  • Non-discardable message exit (early release) - provides you with functionality present in Mainframe IMS that allows messages destined for an abended IMS application program to be deleted, put on the suspend queue, requeued to the original transaction, or routed to an alternate destination.
  • IMS printer support (early release) - IMS application LU1, LU3 MFS, or LTERM output can now be spooled to printers using TCP/IP protocols. You now have the ability to print IMS output on local or networked printers.
    Note: Print spool API support is not available. Users are responsible for associating printers with a user or a department.

OpenESQL

JDBC
JDBC has been enhanced to support two new directives:
JNDI
Enables you to specify a JNDI class that looks up connection strings.
JNDIENC
Enables applications to use the JNDI Environment Naming Context (ENC) when looking up JDBC data source names using JNDI.
ODBC
Added support for a generic one-phase commit for ODBC XA switch module.
SQL Server
We now support Microsoft SQL Server 2012.

Open PL/I

The following enhancements to the Open PL/I feature are now available:

  • Support for WCHAR data types and associated built-in function enhancements. See the Open PL/I Language Reference Manual in the General Reference section of your product help for more information.
  • Support for bigendian CHAR VARYING on Intel chipsets.
  • Support for the following built-in functions: PLICTF, PLIFILL, PLIMOVE, PLIOVER.
  • Support for character picture data types. See the Open PL/I Language Reference Manual in the General Reference section of your product help for more information.
  • Preprocessor for SQL Server (HCOSS).
  • New PLITEST debugger attach facility.
  • Macro Preprocessor enhanced to support multiple closure.
  • Macro Preprocessor enhanced to support up to 100 byte variable names.
  • Macro Preprocessor enhanced to support %SELECT,%DO WHILE,SYSVERSION, ||=
  • Macro Preprocessor support for the -incafter Compiler directive to allow for addition of an include file without modifying the customer sources.
  • The DB2 LUW Precompiler has been enhanced to allow specification of userid and password.
  • Early Adopter Support for Oracle on Windows using the ODBC interface.

General Enhancements

JVM auto-runtime

If you are developing a COBOL JVM project, you don't have to choose whether to use the native or pure JVM file handling systems. You can use just one runtime that configures itself for the environment it is executing in.

Managed code 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: New Features


Features Added in Enterprise Server 2.0

Enterprise Server

Features include:

  • Configuration of enterprise servers using the Administration Web interface.
  • Dynamic debugging of applications that are running under an enterprise server
  • Deployment of mainframe and native code applications to an enterprise server.
  • CICS Web Interface (CWI) Offers an additional CICS Web Interface (CWI) support to include DOCUMENT and EXTRACT TCPIP CICS APIs and to provide support for CICS as an HTTP client.

Support for the PL/I Language

  • The Micro Focus Open PL/I Compiler, Debugger and Runtime are included into the Enterprise Developer and Enterprise Server products to enable Micro Focus to offer a comprehensive, low-risk migration solution for mainframe Pl/I applications.

    Features include:

    • Shared file handling between Micro Focus COBOL and Open PL/I - Open PL/I enables you to use the same filehandler as used by the Micro Focus COBOL products. Its primary advantage is that it provides support for Indexed files and the ability to execute PL/I programs under the control of Enterprise Server JCL.
    • Shared Memory handling and Corruption detection with the Micro Focus COBOL run-time system.
    • Shared Signal Handling with the Micro Focus run-time system.
  • Improved support for large PL/I programs.
  • Supports the WIDECHAR data type (and the built-in functions associated with it).
  • Improved debugging capabilities for applications under development and running in production which help increase the programmers' productivity during and after migration.
  • Support for the PLIDUMP() facility which generates a callstack and shows all static variables, local variables and API parameters that were in effect at the time of the call to PLIDUMP. PLIDUMP is typically used to analyze application failures while running in production.
  • Support for an enhanced PLITEST API which allows for dynamic attachment of the PL/I Debugger at a point the application programmer specifies. In addition, the PLITEST interface now has the capability of displaying the Codewatch Debugger UI on any platform capable of hosting an X-Windows Server.
  • Generation of ASA Control Characters when writing to PL/I files with the STREAM and PRINT attributes. When writing PL/I files that are defined to have the STREAM and PRINT attributes, appropriate control characters are now written to column 1 of the output dataset to represent a new page, skip(1), skip(2), skip(3), and skip(0) (known as overstrike). This helps ease the migration and integration of PL/I applications with existing printing subsystems.
  • OpenESQL for PL/I - Support for Microsoft SQL Server within Open PL/I included within Enterprise Developer and Enterprise Test Server is available as an early adopter release. This provides the option to select Microsoft SQL Server as the target database when migrating PL/I applications that utilize DB2.
    • The mature OpenESQL technology Micro Focus has supported for many years for its COBOL customers, is now available for use with PL/I applications. This means PL/I SQL can now execute against popular relational databases like Microsoft SQL Server even though a SQL preprocessor for PL/I is not available from the database vendor.
    • This support is classified as "Early Adopter". It has been successfully tested by Micro Focus development but has only been exposed to a limited amount of customer application code.
  • The PL/I Dynamic Calls (FETCH/RELEASE) are supported. This provides greater efficiency during migration and less risk as applications using dynamic calls can be rehosted without significant changes to application logic.
  • DB2 UDB Precompiler - A DB2 UDB Precompiler is now available on all platforms for Open PL/I. This feature allows you to migrate applications which contain EXEC SQL logic.
  • Support for the PLISRTx routines to support data types of ZD, PD, FI, BI, and FL.
  • Open PL/I DB2 LUW Preprocessor - the Open PL/I DB2 LUW Preprocessor supports ROWID, BLOB and CLOB which widens the breadth of applications that can be rehosted. Without this support, applications using such features would not be considered as candidates for migration due to the significant reengineering that would be required.
  • Improved Language compatibility with IBM's z/OS based PL/I Compiler - applications that use these IBM mainframe PL/I language features do not need code modification to function in the same manner using Open PL/I. This reduces risk while accelerating migration of such programs.
  • Support for Open PL/I applications that utilize CICS within Enterprise Server. This provides the ability to re-host mainframe PL/I applications to lower cost Windows, UNIX or Linux platforms while keeping PL/I code intact to minimize risk. Features include:
    • A new PL/I CICS precompiler.
    • Enhanced source level debugging.
    • PL/I RTS support for CICS applications.
  • Support for IMS/DB and IMS/TM applications - Open PL/I supports the PLITDLI and PLIHSSR interfaces. Customers who wish to migrate their PL/I Online or Batch applications that utilize IMS can now run them on Enterprise Server.
Parent topic: New Features


Significant Changes in Behavior or Usage in This Release

This release of Enterprise Server might include some significant changes in behavior or usage that could potentially affect the behavior of existing applications or impact the way the tools are used.

For a list of these changes, see this product's Release Notes available from the Product Documentation section of the Micro Focus SupportLine Web site.

Parent topic: Welcome


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.

  • Installation
  • Managing Licenses
  • Updates and Product Support
  • Micro Focus End User License Agreement
  • Backward Compatibility with Server Enterprise Edition
  • Known Errors and Restrictions
  • Contacting Micro Focus
Parent topic: Welcome


Installation

  • Before Installing
  • Basic Installation
  • Advanced Installation Tasks
  • After Installing
Parent topic: Product Information


Before Installing

  • Downloading the Product
  • System Requirements
  • Installation Restrictions and Requirements
  • Product Co-Existence
Parent topic: Installation


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: Before Installing


System Requirements

  • Hardware Requirements
  • Operating Systems Supported
  • Software Requirements
  • Additional Software Requirements
Parent topic: Before Installing


Hardware Requirements

The disk space requirements are approximately:

Enterprise Server | Sentinel RMS License Manager
1.2Gb | 75MB
Note: This includes the space needed to cache information locally so that you can modify the installation without the original source media.
Parent topic: System Requirements
Related information
Operating Systems Supported
Software Requirements
Additional Software Requirements


Operating Systems Supported

For a list of the supported operating systems, check the Product Availability section on the Micro Focus SupportLine Web site: http://supportline.microfocus.com/prodavail.aspx.

Note: This product can be installed on earlier versions of Windows but it has not been tested on them.
Parent topic: System Requirements
Related information
Hardware Requirements
Software Requirements
Additional Software Requirements


Software Requirements

Note:
  • The setup file will check your machine for whether the prerequisite software is installed and will install any missing prerequisites and the product components.
  • This product includes OpenSSL version 1.0.1p.

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

  • The Microsoft .NET Framework - the setup file installs the .NET Framework 4.5.2 . You might need to install the following version of the .NET framework manually, if it is targeted by your applications:
    • Microsoft .NET Framework 2 - if your applications use the ILCLR(2) Compiler Directive or if they target the .NET Framework versions 2, 3 or 3.5. You might need to download these installers depending on the .NET Framework you are targeting.

      To download the Microsoft .NET Framework 2 click here.

      Microsoft .NET Framework 2 or later is also required for the Micro Focus License Manager if you install this on a separate machine as a license server.

    Note:
    • .NET Framework 3 is provided with Windows Vista and Windows Server 2008.
    • .NET Framework 3.5 is provided with Windows 7 and Windows Server 2008 R2.
    • .NET Framework 4.0 is provided with Windows 7 and Windows Server 2008 R2.
    • .NET Framework 4.5 is provided with Windows 8 and Windows Server 2012.
    • .NET Framework 4.5.1 is provided with Windows 8.1 and Windows Server 2012 R2.
  • Microsoft's Web Platform Installer 2.0 if your application targets ASP.NET 4. This installs and sets up ASP.NET. To download the installer click here.
  • A Web browser is required for Enterprise Server Administration in Enterprise Server.

    To use your Web browser offline, you need the dial-up networking feature of Windows installed. Otherwise you might have TCP/IP errors such as being unable find "localhost" or the numeric equivalent (127.0.0.1).

  • To use Enterprise Server Administration, scripting or JavaScript support must be enabled in your browser. This is on by default in Internet Explorer in most Windows operating systems. Also, active content must be allowed and not blocked. To enable both these in Internet Explorer:
    1. Click Tools > Internet Options.
    2. On the Security tab, click Custom Level. In the Scripting section, under Active Scripting, click Enable.
    3. On the Advanced tab, scroll down the list to the Security section, and ensure the item Allow active content to run in files on My Computer is checked.
  • Enterprise Server Help requires the Java Runtime Environment on some Windows systems to enable the Search facility to work.
Important: This release requires version 10000.2.990 or later of the Micro Focus License Administration tool. For local servers, you do not need to install it separately, as the setup file installs a new Enterprise Developer 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. On Windows, you can check the version of your license server by clicking Help > About in the Micro Focus License Administration tool.

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

Parent topic: System Requirements
Related information
Hardware Requirements
Operating Systems Supported
Additional Software Requirements


Additional Software Requirements

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

  • Application Server support for JVM COBOL
  • Application Server JCA support for Enterprise Server
  • Database Access - COBSQL (Pro*COBOL)
  • Database Access - HCO for DB2 LUW
  • Database Access - HCO for SQL Server (HCOSS)
  • Database Access - Mainframe Batch Database Tools (MBDTs)
  • Database Access - OpenESQL
  • Mainframe Access - Endevor Support
  • WebSphere MQ

Application Server support for JVM COBOL

Back to Top

The following application servers are supported using the following JDKs:

Application Servers | JDK version | Containers support version
Tomcat 7.0.39 | 1.7 | Servlets 2.5
JBoss 7.1.1 | 1.7 | Servlets 2.5
WebLogic 12.1.1 | 1.7 | Servlets 2.5
WebSphere 8.5 | 1.7 | Servlets 2.5

You need Oracle's JDK. The earliest supported release of Oracle's JDK 1.7 is 1.7.027. You can download Oracle's JDK from Oracle's Web site.

Application Server JCA support for Enterprise Server

Back to Top

Java EE 5 and Java EE 6 are supported for the deployment of EJBs as follows:

  • Java EE 5 includes support for EJB 3.0 and Java Connector Architecture 1.5
  • Java EE 6 includes support for EJB 3.1 and Java Connector Architecture 1.6

The following Java application servers are supported using the following JDKs:

Application Servers | JDK (vendor) | Java EE | COBOL RA | CICS RA
JBoss 5.1.0 | 1.5/1.6 (Oracle) | 5 | X |
JBoss 6.1.0 | 1.6 (Oracle) | 6 | X |
JBoss 7.1.1 | 1.7 (Oracle) | 6 | X | X
Oracle WebLogic 10.3.5 | 1.6 (Oracle) | 5 | X |
Oracle WebLogic 12.1.1 | 1.6/1.7 (Oracle) | 6 | X |
IBM WebSphere 7.0 | 1.5 (IBM) | 5 | X |
IBM WebSphere 8.0 | 1.6 (IBM) | 6 | X |
IBM WebSphere 8.5 | 1.6/1.7 (IBM) | 6 | X | X

Please consult your Application Server documentation to determine which JDK you should use. The JDK is used to start the Application Server

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

Database Access - COBSQL (Pro*COBOL)

Back to Top

Before deploying a COBSQL application, be sure to install and configure all applicable third-party software.

Note: COBSQL (Pro*COBOL) is supported for native COBOL only.
Availability
Feature/Platform | 32-bit | 64-bit
x86-64 running Windows | X | X
XA Switch Module
The Oracle XA switch module is provided for COBSQL (Pro*COBOL), and is available on the same platforms as are indicated in the Availability section above.
Testing
For this version, COBSQL was tested with Oracle 11.1, 11.2, and 12.1.

Database Access - HCO for DB2 LUW

Back to Top

Before deploying an HCO for DB2 LUW application, be sure to install and configure all applicable third-party software.

Note: HCO for DB2 LUW is supported for native COBOL only.
Availability
Feature/Platform | Native COBOL 32-bit | Native COBOL 64-bit | PL/I 32-bit | PL/I 64-bit
x86-64 running Windows | X | X | X | X
XA Switch Module
The DB2 XA switch module is provided and is available on the same platforms as are indicated in the Availability section above.
Host Compatibility Option (HCO)
Host Compatibility Option requires that you have one of the following software products installed and configured:
  • IBM DB2 Connect - Personal, Enterprise, Application Server or Unlimited Edition
  • IBM DB2 LUW - Workgroup or Enterprise Server Editions including Advanced versions
  • IBM DB2 LUW - Express or Express-C Edition
  • IBM Data Server Client (assumes installation of a remote DB2 LUW Server product)
Testing
For this version, HCO for DB2 LUW was tested with versions 9.5, 9.7, 10.1, and 10.5.

Database Access - HCO for SQL Server (HCOSS)

Back to Top

Before deploying an HCOSS application, be sure to install and configure all applicable third-party software.

Microsoft SQL Server
SQL Server 2008 R2 or later, Developer or Enterprise Editions, including Microsoft SQL Server Management Studio.
Database Migration
  • Microsoft .NET Framework 4.0
  • Microsoft OLE DB Provider for DB2 version 5.0 or later
    Note: Be sure to configure the OLE DB Provider to connect to the mainframe. See your Microsoft documentation for details.
  • Mainframe DB2
Note:
  • We support only the mainframe DB2 versions that are currently under IBM support.
  • If you intend to develop applications on your local machine, but deploy applications to a SQL Server database on a remote machine, you can install SQL Server Native Client 10.x (or later) for ODBC connectivity on your local machine instead of installing SQL Server. For SQL Server 2014 connectivity, you can install Microsoft ODBC Driver 11.0 for SQL Server. For information on configuring a deployment machine, see the section Deploying Native Applications below.
Application Migration
ADO.NET applications
ADO.NET applications require either of the following combinations:
  • SQL Server 2008 R2 and SqlClient Data Provider in .NET Framework 3.5
  • SQL Server 2012 or later and SqlClient Data Provider in .NET Framework 4.0, or 4.5 (4.x is preferred)
Deploying Native Applications
Development Machine
  • Enterprise Developer
  • If SQL Server 2008 R2 or 2012 is not installed, you must have Microsoft SQL Server 2008 R2 or 2012 Native Client installed. For SQL Server 2014, you must have Microsoft ODBC Driver 11.0 for SQL Server.
Development SQL Server Machine
SQL Server 2008 R2 or later
Note: This can be the same machine as the development machine, but is not required to be.
Deployment Machine
  • Enterprise Server or Enterprise Test Server
  • If SQL Server 2008 R2 or 2012 is not installed, you must have Microsoft SQL Server 2008 R2 or 2012 Native Client installed. For SQL Server 2014, you must have Microsoft ODBC Driver 11.0 for SQL Server.
If you want to bind your application from the deployment machine, install the following additional software:
  • Microsoft .NET 3.5 framework, or later
  • SQL Server 2008 R2 or later System CLR Types
  • SQL Server 2008 R2 or later Shared Management Objects
Deployment SQL Server Machine
SQL Server 2008 R2 or later
Note: This can be the same machine as the deployment machine, but is not required to be.
Testing
For this version, HCO for SQL Server was tested with SQL Server 2008 R2, 2012, and 2014.

Database Access - Mainframe Batch Database Tools (MBDTs)

Back to Top

Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability; however, this feature is not intended for production use and it is not supported as such.
Availability
Feature/Platform | 32-bit | 64-bit
x86-64 running Windows | X | X
OpenESQL
The MBDTs are OpenESQL applications, and are native code using ODBC. Please see the Database Access - OpenESQL section for further details.
Testing
For this version, the MBDTs were tested with:
  • DB2 LUW 10.5
  • Oracle 12.1
  • SQL Server 2012

Database Access - OpenESQL

Back to Top

Before deploying an OpenESQL application, be sure to install and configure all applicable third-party software.

Availability
Feature/Platform | Native, ADO.NET Managed, and JVM Managed COBOL 32-bit | Native, ADO.NET Managed, and JVM Managed COBOL 64-bit | PL/I 32-bit | PL/I 64-bit
x86-64 running Windows | X | X | X | X
XA Switch Module
The ODBC One-phase Commit switch module is provided and is available on the same platforms as are indicated in the Availability section above.
Native COBOL and PL/I
  • OpenESQL supports access to relational databases using ODBC 3.0-compliant drivers
  • Refer to your driver vendor's documentation to determine whether your driver is suitable for use with OpenESQL
.NET Managed COBOL
  • OpenESQL supports access to relational databases using compliant .NET framework drivers
  • OpenESQL has been tested against the following ADO.NET data providers:
    • Microsoft provider for SQL Server
    • Microsoft provider for Oracle
    • IBM DB2
    • Oracle Data Provider for .NET (ODP.NET) - fully managed and unmanaged providers
    • OleDb
    • Managed ODBC .NET providers
    • Npgsql PostgreSQL 9.4
JVM Managed COBOL
OpenESQL supports access to relational databases using JDBC 4.0-compliant JDBC drivers. The following table shows the tested DBMSs and their corresponding JDBC driver filenames:
Tested DBMS Versions JDBC 4.0 Compliant Drivers
DB2 LUW 9.5

DB2 LUW 9.7

DB2 LUW 10.1

DB2 LUW 10.5

db2jcc4.jar (and db2jcc_license_cu.jar)
Oracle 11.1, 11.2

Oracle 12.1

ojdbc6.zip1

ojdbc7.zip1

Microsoft SQL Server 2008 R2

Microsoft SQL Server 2012

Microsoft SQL Server 2014

sqljdbc4.jar2
PostgreSQL 9.4
1Some Oracle JDBC drivers are distributed as .zip rather than .jar files.

2 On Windows platforms, if you are not using Windows authentication, no additional resources are required. However, if you are using Kerberos authentication with a driver version of 4.0 or later, although integrated authentication is not required, you might need to follow additional configuration steps as described in the driver documentation. No additional resources are required for UNIX platforms.

To use JDBC DataSource Objects, you must also install and configure a JNDI server.

  • If you are using a Java application server, it includes a JNDI server you can use to configure DataSource objects. This process is described in the Java documentation for the application server.
  • If you are not using a Java application server, or if you require a standalone JNDI server to configure DataSource objects for initial evaluation and development, see the To install and configure Simple-JNDI topic in this documentation set for instructions on downloading, installing, and configuring the open source JNDI server Simple-JNDI for this purpose.
Testing
For this version, OpenESQL was tested with:
  • Oracle 11.1, 11.2 and 12.1
  • DB2 LUW 9.5, 9.7,10.1,10.5
  • SQL Server 2008 R2, 2012, 2014
  • PostgreSQL 9.4
Note: Micro Focus provides compatibility for PostgreSQL but does not directly contribute to or support the PostgreSQL open source project. Any issues relating to PostgreSQL functionality should be addressed through an open source support vendor.

Mainframe Access - Endevor Support

Back to Top

  • To use the Mainframe Access support for Endevor you must be using Endevor R14 or later. CA stabilized the Endevor API at R14, so if you upgrade from R14 to a later version you will not need to update the support module that Mainframe Access uses.

WebSphere MQ

Back to Top

IBM WebSphere MQ version 7 and later.

Parent topic: System Requirements
Related concepts
HCO Tools
Deploying Native Applications
Related information
Hardware Requirements
Operating Systems Supported
Software Requirements


Installation Restrictions and Requirements

Before starting the installation, you should consider the following:

  • You need to be logged in with a user-ID that has write access to the registry structure under HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, and HKEY_CURRENT_USER so the installation software can set the environment appropriately. You also need to be logged on with Administrator privileges.
  • Before installing this product, make sure that any existing Micro Focus Directory Server (MFDS) or CCITCP2 Windows service (on Windows) from an existing product is stopped and uninstalled. On Windows, do this as follows:
    1. Stop the MFDS and CCITCP2, using either the Windows Service Management Console GUI (services.msc) or from a command line prompt by typing:
      net stop mf_ccitcp2

      Only one instance of the MFDS or CCITCP2 service can run on a Windows machine.

    2. Uninstall the MFDS or CCITCP2 service.

      For MFDS, from a command line prompt enter: mfds -u

      For CCITCP2: ccitcp2 -u

    To run an earlier version of MFDS as a service after you have installed a later version:

    1. Stop and uninstall the MFDS service, as described above.
    2. Reinstall the earlier version, as follows:
      1. Open an Enterprise Server command prompt.
      2. Install the service. Enter the following command: mfds -i
      3. Start the service. Enter the following command: net start mf_ccitcp2
      Note: The two versions use different paths for environment and registry values, so the list of configured enterprise servers might be different depending on which version has been started, since, by default, different MFDS data repositories are used.

    MFDS 5.1 and later are able to import or use Enterprise Server configuration data generated by earlier versions of MFDS, but 5.0 or earlier versions of MFDS might not be able to read data generated by later versions.

    It is possible to run MFDS from a command prompt ("mfds") rather than as a service, but by default the "mfcobol" port is used (86) and this can only be used by one process at a time

Parent topic: Before Installing


Product Co-Existence

  • Enterprise Developer and Enterprise Server (or Enterprise Test Server) cannot coexist on the same machine.
  • Enterprise Server and Enterprise Test Server cannot coexist on the same machine.
Parent topic: Before Installing


Basic Installation

The instructions in this section apply when you are performing a basic installation of this product for the first time. If you are an administrator, you can perform a basic installation on a local machine before performing a more advanced installation when rolling out the product to developers within your organization.

For considerations when installing this product as an upgrade, for additional installation options or non-default installations and for installing the mainframe components, see Advanced Installation Tasks.

  • Installing
Parent topic: Installation


Installing

Note: If there is an earlier version of Enterprise Server installed on your machine, check Installing as an Upgrade first.

These are the steps to install this product:

  1. Run the es_231.exe file and follow the wizard instructions to install the prerequisite software and the product.

    The setup file will also install any missing prerequisite software as listed in Software Requirements.

Note:
  • If you are installing onto a machine that has an existing Micro Focus product that uses an older Sentinel RMS License Manager, you might be prompted to remove it and install the Micro Focus License Administration. By doing this you maintain the existing Sentinel RMS license files while adding the Micro Focus License Administration. If you are unsure about existing licenses on your computer or removing the Sentinel RMS License Manager, consult your System Administrator. If you want to proceed, remove Sentinel RMS License Manager by using Program and Features (Windows Vista or later), and rerun the installation file.
  • Trial licenses cannot be used with remote desktop services. If you want to use your product in this way, please contact Micro Focus SupportLine to obtain a relevant license.
  • We recommend that you install any updates for the .NET Framework that are available at the Microsoft Download site.
  • If you install JDK you might be prompted to install the latest update. The latest update is not required for use with Enterprise Server but you can install it if you wish.
Parent topic: Basic Installation


Advanced Installation Tasks

This section includes instructions about how to perform a non-default installation, install this product as an upgrade, or about how to install any additional components.

  • Installing as an Upgrade
  • Enterprise Server Installation Options
    Describes the different ways in which you can install Enterprise Server.
Parent topic: Installation


Installing as an Upgrade

Before installing, check Installation Restrictions and Requirements.

Installing this release as an upgrade will automatically uninstall any HotFixes of the older version of the product you have installed on your machine.

  • Before installing this release as an upgrade, ensure you create a back-up of your Enterprise Server configuration. To do this, on the Enterprise Server Administration home page, click Export and then select Export Enterprise Server configuration and Security Manager definitions. This creates a backup folder in the c:\programdata\micro focus\Enterprise Developer\MFDS. You can restore the Enterprise Server configuration after installing this release - click Import on the Enterprise Server Administration home page.
Parent topic: Advanced Installation Tasks


Enterprise Server Installation Options

To install Enterprise Server you run es_231.exe which contains a number of product .msi files (Windows Installer packages). When run, es_231.exe performs some initial system checks then sequentially installs the .msi files.

es_231.exe can take a number of parameters, enabling you to specify a number of different types of installation:

  • Standard Installation
    • Format:
    • es_231.exe
    • Summary:
    • Full installation including License Manager and Enterprise Server. During installation you can specify options including the location to which the components are installed.
  • Non-interactive Installation
    • Format:
    • es_231.exe /passive
    • Summary:
    • Full installation, but the components are installed non-interactively using default options and directories.
  • Silent Installation
    • Format:
    • es_231.exe /q
    • Summary:
    • Full installation, but the components are installed non-interactively with no user interface, using default options and directories.
  • Modified Silent Installation
    • Format:
    • es_231.exe /q InstallFolder=d:\cobolrts
    • Summary:
    • Full installation, but the components are installed non-interactively with no user interface, and Enterprise Server is installed to d:\cobolrts.

To see what parameters you can use, execute the following from the command line: es_231.exe /?.

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.
Parent topic: Advanced Installation Tasks


After Installing

  • See Changes in Behavior or Usage for important information about changes in this release that might affect existing applications.
  • Check the Product Documentation section of the Micro Focus SupportLine Web site and the Micro Focus Infocenter for any updates to the documentation which might have been uploaded.

Also, note the following:

  • Repairing
  • Uninstalling
Parent topic: Installation


Repairing

If any product files, registry settings or shortcuts are accidentally removed at any point, you can perform a repair on the installation to replace them.

To repair your installation on versions of Windows Vista or later:

  1. From the Control Panel, click Uninstall a program under Programs.
  2. Right-click your Micro Focus product and select Repair.
Parent topic: After Installing


Uninstalling

To uninstall the product, you cannot simply delete its files from your hard disk. To uninstall the product:

  1. Log in with the same user-ID as you used when you installed the product.
  2. Click Uninstall a program under Programs in Control Panel.
  3. Select the product and click Remove or Uninstall as appropriate.

When you uninstall, the only files deleted are those that the installation software installed. If the product directory has not been removed, delete any unwanted files and subdirectories within it using Windows Explorer.

Important: The installer creates separate installations for Micro Focus Enterprise Server and Micro Focus License Administration. Uninstalling only Enterprise Server does not automatically uninstall the Micro Focus License Administration or any of the prerequisite software.

To completely remove the product you must uninstall the Micro Focus License Administration as well.

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

To silently uninstall the product, you need the setup file and you need to execute the following at the command line:

start /wait install-file.exe /quiet /uninstall
Parent topic: After Installing


Managing Licenses

  • Overview
  • To start Micro Focus License Administration
  • Installing licenses
  • Installing licenses silently
  • Viewing installed licenses
  • Uninstalling licenses
  • Trial licenses
  • Commuter licenses
  • Usage log
  • Licensing Error Messages
    Messages you might encounter when working with licensing.
Parent topic: Product Information


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
Related concepts
Overview of Deploying Native COBOL Applications


To start Micro Focus License Administration

From the Windows Taskbar click Start > All Programs >Micro Focus License Manager > License Administration.
Note: On Windows 8, Windows 10, and Windows Server 2012, you use the Start screen to invoke programs.
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 Micro Focus License Administration.
  2. Click the Install tab.
  3. Do one of the following:
    • Click Browse next to the License file field and select the license file (which has an extension of .mflic).
    • Drag and drop the license file from Windows Explorer to the License file field.
    • Open the license file in a text editor, such as Notepad, then copy and paste the contents of the file into the box below the License file field.
  4. Click Install Licenses.
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. Click the Install tab.
  3. Type the authorization code in the Enter authorization code field.
  4. Click Authorize.

If you change the name of the machine running your license server after it has granted licenses, the licenses stop working.

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.

  1. Start Micro Focus License Administration.
  2. Click Manual Authorization on the Install page.
  3. Make a note of the contents of the Machine ID field. You will need this later.
  4. Do one of the following:
    • If your machine has an Internet connection, click the SupportLine Web link in the Manual Authorization Information window.
    • If your machine does not have an Internet connection, make a note of the Web address and type it into a Web browser on a machine that has an Internet connection.

    The Micro Focus SupportLine Manual product authorization Web page is displayed.

  5. Type the authorization code in the Authorization Code field. The authorization code is a 16-character alphanumeric string supplied when you purchased your product.
  6. Type the Machine ID in the Machine ID field.
  7. Type your email address in the Email Address field.
  8. Click Generate.
  9. Copy the generated license string (or copy it from the email) and paste it into the box under the License file field on the Install page.
  10. Click Install Licenses.
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 Options > Advanced Configuration.
  3. Click Change next to License server.
  4. In the New value field, type the IP address or server name for the network license server.
  5. Click Save.
  6. Close the Advanced Configuration window.
  7. Click File > Exit.
Parent topic: Installing licenses


Installing licenses silently

Note: Micro Focus recommends that you use the Micro Focus License Administration tool to install the licenses. You may only need to install licenses silently in some specific scenarios - for example, as part of a silent installation when you are distributing COBOL server with your applications.

After the application installation is complete you can install the license silently by executing the following commands:

  • If you have access to the Internet and an authorization code, execute the following commands:

    For 32-bit Windows environments:

    start /wait "" "C:\Program Files\Common Files\SafeNet Sentinel\Sentinel RMS License Manager\WinNT\cesadmintool" -term activate AuthorizationCode

    For 64-bit Windows environments:

    start /wait "" "C:\Program Files (x86)\Common Files\SafeNet Sentinel\Sentinel RMS License Manager\WinNT\cesadmintool" -term activate AuthorizationCode
  • If you don't have access to the Internet but have a file from Micro Focus that contains the license string:

    For 32-bit Windows environments:

    start /wait "" "C:\Program Files\Common Files\SafeNet Sentinel\Sentinel RMS License Manager\WinNT\cesadmintool" -term install -f FileName

    For 64-bit Windows environments:

    start /wait "" "C:\Program Files (x86)\Common Files\SafeNet Sentinel\Sentinel RMS License Manager\WinNT\cesadmintool" -term install -f FileName

    where FileName is the name of the text file that contains all the license strings to be used.

  • If you have access to the Internet and an authorization code, run the following as root:
    cd /var/microfocuslicensing/bin
./cesadmintool.sh -authorize AuthorizationCode
  • If you don't have access to the Internet but have a file from Micro Focus that contains the license string, run the following as root:
    cd /var/microfocuslicensing/bin
./cesadmintool.sh -install FileName

    where FileName is the name of the text file that contains all the license strings to be used.

Parent topic: Managing Licenses


Viewing installed licenses

Start the Micro Focus License Administration tool. The Summary page shows detailed information about the licenses installed on a machine.

Licenses with extra information have a link enabled in the Type column. This information includes the type of license, number of users, the date the license was generated, and the platform it is for. Click this link to view extra information about that license.

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. Click the Summary tab.
  3. On the Summary page, select the product license you want to uninstall.
  4. In the Uninstall column, click Remove.
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.

  1. Start Micro Focus License Administration.
  2. Click the Summary tab.
  3. On the Summary page, select the product license you want to revoke.
  4. In the Uninstall column, click Revoke.

    After a check is made to ensure no licensed products are running, the Revoke Product Licenses dialog box is displayed.

  5. Specify the number of licenses you want to revoke.
  6. Click Revoke.

A new authorization code for each revoked license is generated and saved to a file on your computer. The file location and the new codes are displayed on the screen.

Ensure that you keep the new authorization codes in a safe place. You need them to reauthorize products.

Important: If there is a problem accessing the Micro Focus License Authorization Server and the revocation fails, the Revoke Product Licenses dialog box enables options to allow manual revocation. At this point, your licenses are revoked and cannot be used. To obtain an authorization code, you must send the License Revocation Tickets (LRTs) to Micro Focus, either by pasting them into the revoke Web page or by sending the indicated file to your SupportLine representative.
  1. Copy the whole character string displayed in the text box at the bottom of the Revoke Product Licenses dialog box. This string contains the License Revocation Tickets (LRTs) that are required to issue a new authorization code.
  2. Click the web page link to open the Micro Focus SafeNet License Revocation Web page.
  3. Paste the copied string in the text box, then click Generate.

    The new authorization code is displayed. Ensure you keep the new codes in a safe place as you need them to reauthorize products.

  4. Copy the whole character string displayed in the text box at the bottom of the Revoke Product Licenses dialog box.
  5. Paste the string 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.
  1. Start Micro Focus License Administration.
  2. Click the Summary tab.
  3. On the Summary page, select the product license you want to revoke.
  4. In the Uninstall column, click Revoke.

    An error message is displayed confirming there is no Internet connection.

  5. Copy the whole character string displayed in the text box at the bottom of the Revoke Product Licenses dialog box. This string contains the License Revocation Tickets (LRTs) that are required to issue a new authorization code.
  6. Click the web page link to open the Micro Focus SafeNet License Revocation Web page.
  7. Paste the copied string in the text box, then click Generate.

    The new authorization code is displayed. Ensure you keep the new codes in a safe place as you need them to reauthorize products.

  8. Copy the whole character string displayed in the text box at the bottom of the Revoke Product Licenses dialog box.
  9. Paste the string 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, a Commuter tab is displayed in the Administration tool window.

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. Click the Commuter tab.

    A list of commutable products is shown on the Commuter page.

  3. Select the product you want to commute and click Commute.

    A dialog box is displayed allowing you to select the number of days you want to commute the license for.

Commuted licenses appear in the Commuted here column with the number of days remaining in the commute period.

Parent topic: Commuter licenses


To return a commuter license

  1. Start Micro Focus License Administration.
  2. Click the Commuter tab.
  3. Select the appropriate product and press Return License.
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:
  • Windows XP: C:\Documents and Settings\All Users\Application Data\Micro Focus
  • Windows 7: C:\ProgramData\Micro Focus

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 service 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 service is running.

The service is called MF CES daemon. Check if it is running and start it using the Control Panel > Services dialog box.

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


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


Backward Compatibility with Server Enterprise Edition

  • You can export the Server Enterprise Edition configuration and import it into Enterprise Server.
  • Application executables built to run under Server Enterprise Edition must be rebuilt using Enterprise Developer to enable them to operate under Enterprise Server.
Parent topic: Product Information


Known Errors and Restrictions

The following known errors and restrictions apply to Enterprise Server:

  • ADAM on Microsoft Vista and Windows Server 2008
  • Application-Managed Services
  • Documentation
  • Enterprise Server
  • Error Messages
  • FaultFinder
  • File Handler
  • GDG Limit Change
  • HCO for SQL Server (HCOSS)
  • J2EE Third Party Software
  • Mainframe Subsystem Support (MSS)
  • JCL
  • Network File Access
  • OpenESQL
  • Run-Time System
  • Security
  • Security Management
  • Security and SNMP
  • Spool File Format Change
Parent topic: Product Information


ADAM on Microsoft Vista and Windows Server 2008

ADAM (Active Directory Application Mode) is not supported by Microsoft on Vista and Windows Server 2008. If you are configuring Enterprise Server external Security Managers on the Vista platform, a remote Active Directory server should be used instead of ADAM. On Windows Server 2008, Microsoft has provided AD LDS (Active Directory Lightweight Directory Services) as a replacement for ADAM. External Security Managers which use AD LDS can be set up and used in a similar fashion to Security Managers that use ADAM.

Parent topic: Known Errors and Restrictions


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


Documentation

Each help topic in the documentation for Enterprise Server includes a link that enables you to send us an email to provide feedback about the documentation.

For these links to work you must first have defined a mailto: handler. Clicking one of these links when no mailto: handler is defined results in unpredictable behavior.

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 .
Enterprise Server Administration

If you are using Enterprise Server Administration with Microsoft Vista 2008, you may see an Interactive services dialog detection dialog box displaying the message A program can't display a message on your desktop when Enterprise Server attempts to display console messages. You can view the console messages by clicking Show me the message in the dialog box.

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 Enterprise 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.

Performance monitoring - dynamic binding error

If you have two or more products installed that contain core Enterprise Server technology, then performance monitoring via Windows performance counters is only possible against the most recently installed (or repaired) product.

Further, if you install any one product, you will uninstall the performance monitoring capability for all products. This can be restored by a repair installation of the remaining product against which you wish to perform monitoring.

If you have a version of the COBOL runtime loaded and try to acquire performance monitors, the installed cas0perf.dll must have been built with the runtime from the same product. If not, you are likely to get a dynamic binding error because an attempt will be made to bind to the runtime that is already loaded, for example:
Dynamic binding error on run-time entry point mF-Id_dynlnk ...

If you do not need Enterprise Server performance monitoring, you can disable the capability completely by creating a new DWORD registry entry called Disable Performance Counters under HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\Micro Focus Server\Performance and assigning its value to 1.

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


FaultFinder

The FaultFinder tool has been removed from the current version of Enterprise 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.

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 Enterprise 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


HCO for SQL Server (HCOSS)

  • HCOSS SQL Server databases created with an Enterprise Developer version of 2.2 Update 2 HotFix 3 or earlier might be missing HCOSS-provided scalar functions. To ensure your scalar functions are up to date, run the InstallDigitsFunction.sql script against each of your HCOSS databases. The script is located by default in the %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss directory. The user running the script must have read, update, and create permissions for the database SYSIBM and dbo schemas.
  • Starting with Enterprise Server 2.2 Update 1, HCOSS is not backwardly compatible with HCOSS databases created in earlier versions, and that also fit the following description:
    • Use a 64-bit Enterprise Server
    • SQL Server stored procedures called from an ODBC application
    • Use DBRMLIB

    To restore compatibility, use Enterprise Developer to recompile just the programs that call stored procedures. This resolves runtime error messages and greatly improves the performance of the calls to stored procedures.

    For example, if you have a 64-bit HCOSS application that uses SQL compiler directive options DBMAN=ODBC and DBRMLIB, recompile programs that call stored procedures from COBOL or PL/I code.

Parent topic: Known Errors and Restrictions


J2EE Third Party Software

  • IBM WebSphere issues various warnings when running some applications. These are WebSphere problems. For example:
    07/12/10 11:35:55:843 JST] 00000056 PrivExAction W
J2CA0144W: Could not find
a mappingConfigAlias for the connection ...
07/12/10 11:35:55:908 JST] 00000056 PrivExAction W
J2CA0114W: Could not fing a container managed credential alias ...

    You need to specify a container-managed authentication alias for the data source or connection factory, or configure the application to use component-managed authentication. For more details on these warnings, see the IBM Support Web site.

    -547718

  • When using XA transactions with EJB 3.0 on Websphere 7 with the EJB 3 Feature Pack, if there are two resource managers and one of them is ES and the other is using JDBC, if the JDBC update fails, the Transaction Manager in Websphere does not receive the failure message and hence does not send a rollback to the other resource manager or managers (Enterprise Server included). Instead, it sends a commit which is incorrect. This issue is being investigated.

    -557021

Parent topic: Known Errors and Restrictions


Mainframe Subsystem Support (MSS)

Using the ECI interface with the CICS Transaction Gateway

If you have clients using the ECI interface with the CICS Transaction Gateway to communicate with a CICS application running in MSS, a client program might receive an ECI_ERR_TRANSACTION_ABEND return code with an abend code of AZTY, indicating that several clients tried to communicate with the system at the same time but not all requests could be satisfied by MTO. The workaround for this issue is to set the environment variable TX_UNICLI_SESSIONS to the required number of sessions in the Configuration Information for the enterprise server as follows:

[ES-Environment]
TX_UNICLI_SESSIONS=<required-number-of-sessions>

The default is 4.

You should set Maximum requests in the Client Section of the CICS Transaction Gateway configuration to the same value.

If you do this you will also probably need to change the client program to ignore the ECI-ERROR_MAX_SESSIONS return code and retry the call. For example:

do
 {
   Rc = CICS_ExternalCall (&EciParms);
 } while (Rc == ECI_ERR_MAX_SESSIONS);

If you do not make this modification, the client program might still receive the ECI_ERR_TRANSACTION_ABEND return code.

Emulation is not available for the DSNTIAUL and DSNUTILB mainframe utilities.

The casstart command

You can only invoke the casstart command from the command line or from the Micro Focus Directory Server (MFDS); it cannot be invoked, for example, from a batch job.

Parent topic: Known Errors and Restrictions


JCL

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.
  • You cannot restart jobs that have been hard-killed, as they no longer possess the job information required for a restart.
Parent topic: Known Errors and Restrictions


Network File Access

When you deploy a COBOL application as a Web Service or an Enterprise JavaBean, then run it using the default configuration of Enterprise Server, it can no longer open files across a network using drive mappings or UNC paths (that is, file pathnames of the form \\server\share\path\to\file). This is the result of Windows working the way it was designed to and there is no simple workaround that is satisfactory for every customer.

When a program opens a file on another computer (the file server) using a UNC path, Windows uses that program's current security information to try to authenticate it to the server and obtain authorization from the server for access to the file. If the file server does not accept the program's security credentials, the program cannot open the file. These credentials include user login information (the equivalent of a username and password) and other technical details including whether the credentials can be used for network access. If an interactive user runs a program from the desktop or command line, that process runs with the user's credentials. When the program attempts to open a file on a file server, the user's credentials are checked for access.

When a drive letter is mapped to a network share and used to open a file, Windows uses the same mechanism as for UNC paths. However, a drive letter mapping generally applies only to a specific user. A different user on the same computer can have that drive letter mapped to a different share or not mapped at all.

This means that UNC paths represent the same file for every program, no matter which user account the program is running under but that drive letter mappings can vary and are less likely to work when a program is run by different users. In general, UNC paths are more suitable for filenames that are stored in programs or saved somewhere and drive letter mappings are more suitable for interactive use. [1052982]

Parent topic: Known Errors and Restrictions


OpenESQL

ADO.NET

Be aware that when using ADO.NET with Oracle .NET providers that the original, partially managed, provider and the current, fully managed provider behave differently in some scenarios. If your ADO.NET applications behave differently when switching between these Oracle providers, carefully check that you have the providers configured appropriately.

ODBC

When using Oracle's ODBC driver, array fetches and some scrolling fetches might produce inconsistent behavior if you change the array size between fetches. To overcome this, build your application with SQL(NORESULTARRAY). When this is set, OpenESQL performs single row fetches under the covers, bypassing this limitation.

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

Micro Focus COBOL applications deployed to environment such as ASP.NET/Network drives are currently required to have full trust.

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


Security and SNMP

The Micro Focus Audit Manager Configuration supporting includes both node and port address options. These are used to specify the location of the Management Console that will receive the SNMP Trap events that are generated by the auditor.

When using WinSNMP as the local agent these location parameters may be ignored by the Windows implementation of the WinSNMP interface. This can happen if the system has a valid configuration of Microsoft's SNMP service agent for the "public" community. If the SNMP agent configuration is present this is used by the WinSNMP instead of the Micro Focus location options even if the Microsoft SNMP system service is not actually running at the time.

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 Enterprise 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 Enterprise 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
  • Contact information
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 Product Updates section of the Micro Focus SupportLine Web site, where you can download fixes and documentation updates.
  • The Examples and Utilities section of the Micro Focus SupportLine Web site, including demos and additional product documentation.
  • The Support Resources section of the Micro Focus SupportLine Web site, that includes troubleshooting guides and information about how to raise an incident.

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

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.

Also, visit:

  • The Micro Focus Community Web site, where you can browse the Knowledge Base, read articles and blogs, find demonstration programs and examples, and discuss this product with other users and Micro Focus specialists.
  • The Micro Focus YouTube channel for videos related to your product.
Parent topic: Contacting Micro Focus
Related information
Micro Focus SupportLine
Examples and Utilities
Support Resources
Micro Focus Community
White Papers and Webcasts
Micro Focus YouTube Channel


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.

Parent topic: Contacting Micro Focus


Contact information

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

Additional technical information or advice is available from several sources.

The product support pages contain considerable additional information, including the Product Updates section of the Micro Focus SupportLine Web site, where you can download fixes and documentation updates. To connect, enter http://www.microfocus.com in your browser to go to the Micro Focus home page, then click Support.

If you are a Micro Focus SupportLine customer, please see the Welcome to Customer Care document that includes information about downloading and licensing your product, contacting Customer Care, and about reporting an incident. You can download it from our Web site. Support from Micro Focus may be available only to customers who have maintenance agreements.

Parent topic: Contacting Micro Focus
Related information
Micro Focus Web Site
Micro Focus SupportLine
Welcome to Customer Care


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


Help on Help

The latest up-to-date Help is available on the Micro Focus Infocenter on the Web, at http://documentation.microfocus.com.

Help in the Infocenter

Tips on using the Infocenter Help:

  • You can specify the scope of Help to search, by creating your own search lists. To do this, click Scope and follow the wizard instructions. To read more information on how to create a scope, click Infocenter Help, Infocenter Help.
  • The topic in the documentation displayed in the right frame can get out of step with the Table of Contents in the left frame. This can occur when you choose the topic from a search list or when you link to it from another topic. To show where the topic appears in the contents, click Show in Table of Contents, Show in Table of Contents, on the toolbar.
  • You can navigate the Help using the following keystrokes:
    Alt+left arrow/Alt+right arrow | Go back/forward.
    Alt+C | Move to the Contents tab.
    Alt+R | Open Search Results tab.
    Alt+S | Move to the search entry field.
    Ctrl+Tab or Ctrl+F6 depending on your browser | Go to the next frame or toolbar.
    Left arrow/Right arrow | Collapse/expand a tree node.
    Shift+Ctrl+Tab or Shift+Ctrl+F6 depending on your browser | Move to the previous frame or toolbar.

Release Notes

The Release Notes accompany major releases and updates. They are available from the Product Updates section on the Micro Focus SupportLine Web site and your EPD email. On Windows, a link to the release notes is available from the startup screen during installation.

The Release Notes include information about new features for the release, system requirements and installation instructions, known technical issues, information about the issues that are resolved in the current release, and any changes in behavior that could potentially affect existing applications.

Readmes

This documentation includes two types of readmes:

  • HotFix readmes contain information about issues that are resolved in a HotFix, changes in behavior that could potentially affect existing applications, and any specific HotFix installation procedures.
  • Samples' readmes contain information about how to install and execute a sample.

Unless otherwise stated, references to a "readme" will refer to a HotFix readme.

Parent topic: Welcome


Deploying COBOL Applications

Describes the concepts and tasks involved in deploying COBOL applications using Enterprise Server.
  • Deploying Native COBOL Applications
  • Enterprise Server
  • Deploying COBOL Applications to the .NET Environment
    This chapter explains how to deploy COBOL applications to the .NET environment.
Parent topic: Micro Focus Enterprise Server 2.3 Update 1 for Windows


Deploying Native COBOL Applications

Note: The information in this section applies to native COBOL only.
  • Overview of Deploying Native COBOL Applications
  • Shipping Selected Files from Enterprise Server
  • Run-time Launch Configuration Files
    Use a run-time launch configuration file to ensure an application can be launched when it is deployed in a separate location to the run-time system (in the case of dynamically bound applications), or when the licensing daemon is not already running.
  • Writing Your Own Setup Program
  • To set up an application with a shared Enterprise Server
  • To set up an application with its own Enterprise Server
  • To run a native COBOL application from a network server
    You need to configure the licensing for Enterprise Server when running native COBOL applications from a network server.
Parent topic: Deploying COBOL Applications
Related concepts
Deploying Native Applications


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.

Enterprise Server is your COBOL run-time server. It is supplied as part of Enterprise Developer, which is your COBOL development system. Enterprise Server is also supplied separately, and provides the execution environment for applications created with any IDE variant of Enterprise Developer.

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 Enterprise Server with your application, if it is a modular application. We recommend that you ship the whole of Enterprise Server to avoid compatibility issues and other problems.
  • Ensure that the application you have developed has the proper Enterprise Server licenses. Your end users need to install the licenses before they can run the application. This is done by using the Micro Focus License Administration Tool. The 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.
Parent topic: Deploying Native COBOL Applications
Related tasks
Overview


Shipping Selected Files from Enterprise Server

Note: The following applies to native COBOL only.
CAUTION:

We recommend that you ship the whole of Enterprise Server with your application. However to provide backward compatibility, you can still select and ship specific files.

The Enterprise 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. The files that you need to ship also depend on whether your application is single or multi-threaded.

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 that is dynamically linked, 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
  • The file for the shared run-time system, one of the following:
    • cblrtss.dll for single-threaded applications
    • cblrtsm.dll for multi-threaded applications
  • 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
  • OO COBOL Files to Ship
  • Run-time System Files to Ship
Parent topic: Deploying Native COBOL Applications


OO COBOL Files to Ship

Note: The following applies to native COBOL only.
CAUTION:

We recommend that you ship the whole of Enterprise Server with your application. However to provide backward compatibility, you can still select and ship specific files.

If your application uses OO programming, you need to ship the following files:

If your application requires: Single-threading files needed: Multi-threading files needed:

OO programming support

  • class.dll
  • classs.dll
  • mfos.dll
  • oopss.cfg
  • oopss.dll
  • class.dll
  • classm.dll
  • mfom.dll
  • oopsm.cfg
  • oopsm.dll

Java and COBOL mixed language support, depending on the JVM used by the application

  • javaclass.dll (OO Java domain class library)
  • mfcobol.jar (Java classes for accessing COBOL)
  • mfjavam.dll (OO java domain)
  • javaclass.dll (OO Java domain class library)
  • mfcobol.jar (Java classes for accessing COBOL)
  • mfjavam.dll (OO java domain)
Parent topic: Shipping Selected Files from Enterprise Server


Run-time System Files to Ship

Note: The following applies to native COBOL only.
CAUTION:

We recommend that you ship the whole of Enterprise Server with your application. However to provide backward compatibility, you can still select and ship specific files.

If you require support for: | Single-threading files needed: | Multi-threading files needed:
CBL_EXEC_RUN_UNIT (graphical user interface applications) | cblxecws.exe | cblxecwm.exe
CBL_EXEC_RUN_UNIT (character user interface applications) | cblexecs.exe | cblexecm.exe
Character user interfaces (for true console applications only) | cblvios.dll | cblviom.dll
Character user interfaces (for applications that use the default COBOL text window) | cbldwins.dll | cbldwinm.dll
File handling, for enhanced ACCEPT/DISPLAY syntax (ADIS), and for OO persistence | mffh.dll | mffh.dll
Print support module | cblprnt.dll | cblprnt.dll

Other run-time support files that you might need to ship depending on the functionality that your application uses are as follows:

If your application uses: Files needed:
Btrieve
  • xfh2btr.gnt
  • _btrv.gnt
Command-line Sort
  • mfsort.exe

CCI:

  • CCISMEM protocol
  • TCP/IP protocol
  • TCP2 registration

  • ccismem.dll
  • ccitcp.dll
  • ccitcp2.exe
Client/server binding
  • mfcsmgr.int
  • mfserver.int
  • mfclient.int
File handling
  • xfh2btr.gnt (access to btrieve files)
Fileshare
  • fs.dll (server)
  • fs.exe (server trigger)
  • fsservice.exe (to run as an NT service)
  • fsclose.exe (server closedown support)
  • fsmgr.dll (manager API support)
Host Compatibility Option
  • mfhcolib.lbr (when using the DB2 ECM compiler)
  • mfsqlsmf.dll

Micro Focus run trigger program:

  • multithreaded trigger
  • multithreaded trigger (Windows)
  • single-threaded trigger
  • single-threaded trigger (Windows)

  • run.cfg
  • run.exe
  • runm.exe
  • runmw.exe
  • runs.exe
  • runsw.exe
  • runw.exe
  • shell.dll
  • utils.dll
Microsoft Transaction Server
  • objectcontext.dll
ODBC
  • drivers obtained separately, and
  • odbcrw32.dll
Rebuild facility (command-line file recovery tool)
  • rebuild.exe
  • the language files in the relevant lang subfolders. These files need to be available, and the COBDIR environment variable needs to point to the directory containing them
SQL, ESQL and ODBC
  • csqlsupp.dll (Cobsql)
  • odbcrw32.dll or odbcrw64.dll (OpenESQL)
  • oesqlebc.dll (OpenESQL with EBCDIC data)
  • ODBC drivers obtained separately
  • mfsqlsmf.dll
Web Services support
  • gk-os.dll
  • gk-utility.dll
  • mclient.dll
  • mfclsoap.dll
  • mfidmap.dll
  • nxwscrun.dll
  • xerces-c_2_1_0.dll
Parent topic: Shipping Selected Files from Enterprise Server


Run-time Launch Configuration Files

Restriction: These configuration files are supported for native COBOL, and only in a Windows environment.

You can use a run-time launch configuration file to configure certain aspects of application initialization for these deployment scenarios:

  • A dynamically-bound application in which the Enterprise Server run-time files have been included directly within the application, and where there is a requirement to keep these files in a separate directory to the application executables that use them.
  • An application that is run on a machine on which the licensing daemon may not already be running, in which case, the licensing daemon needs to be started automatically before executing the application.

For such deployment scenarios, use a launch configuration file to specify where the application can locate the run-time files, and to ensure the licensing daemon is running.

There are two types of launch configuration file: an application launch configuration file, containing configuration for the specific application, and a default application launch configuration file, containing a default configuration that can be used with any application.

The configuration files are text files, which must be stored in the same directory as the executable when it is run. When naming the files, the application launch configuration filename must consist of the full name of the application executable (including extension), with the extension .mfcfg. For example, an application executable called myapp.exe requires a configuration file called myapp.exe.mfcfg. The default application launch configuration filename is always named mfdefault.exe.mfcfg.

Settings in an application launch configuration file take priority over settings in a default application configuration file if both files exist. If neither launch configuration file exists, the application is launched according to the options that were set during Enterprise Server installation.

  • Run-time Launch Configuration File Options
  • Examples of a Run-time Launch Configuration File
Parent topic: Deploying Native COBOL Applications
Related concepts
To run a native COBOL application from a network server
To run a .NET COBOL application from a network server


Run-time Launch Configuration File Options

Create an appropriately named text file, specifying the following run-time and licensing options (one valid option per line), then deploy it to the same directory as your application.

Option | Description
Run-time options
set SERVERPATH=path-name Specifies the name of the directory containing a Enterprise Server installation that is to be used by the application executable.

path-name can be either an absolute or UNC path, or a path relative to the current directory.

Only specify this option if the executable is built using dynamic linking.

Run-time options are optional, but if set, only one option (SERVERPATH or BINPATH) may be specified.

set BINPATH=path-name Specifies the name of the directory containing the binary run-time files that are to be used by the application executable.

path-name can be either an absolute or UNC path, or a path relative to the current directory.

Only specify this option if the executable is built using dynamic linking.

Run-time options are optional, but if set, only one option (SERVERPATH or BINPATH) may be specified.

Licensing options
set CESDYNAMIC=file-name
Note: This is optional, but if specified, it must appear after any entry for SERVERPATH or BINPATH.

Specifies the name of a CES configuration file (usually named CES.INI), which is used to initialize the licensing daemon, if it is not already running.

If this option is not specified, the licensing daemon must already be installed and running on this machine.

If file-name includes a directory name, the CES configuration file in that directory is used.

If file-name does not include a specific directory then, if either SERVERPATH or BINPATH is specified, the CES configuration file should be located on the specified path (for BINPATH) or the bin or bin64 directory on the specified path (for SERVERPATH). In all other cases, the CES configuration file should be in the same directory as the main application executable.

When specifying this option, the files mfcesd.exe (the Micro Focus licensing daemon) and mfcesdchk.exe (which checks if the Micro Focus licensing daemon is running) are also required. On a machine with licensing already installed, these can be found in the following locations:

  • 32-bit Windows: C:\Program Files\Common Files\SafeNet Sentinel\Sentinel RMS License Manager\WinNT
  • 64-bit Windows: C:\Program Files (x86)\Common Files\SafeNet Sentinel\Sentinel RMS License Manager\WinNT
Deploy these files to one of the following locations:
  • In a directory that is already on the system PATH when the application is executed.
  • The bin (for a 32-bit application) or bin64 (for a 64-bit application) directory of the Enterprise Server installation specified by SERVERPATH.
  • The directory specified by BINPATH.
#comment-line | Comment line. Content on this line is not processed.
Parent topic: Run-time Launch Configuration Files
Related reference
Examples of a Run-time Launch Configuration File


Examples of a Run-time Launch Configuration File

The following examples are valid entries for either an application launch configuration file or a default application launch configuration file.

The following example binds the application (built with dynamic binding enabled) to Enterprise Server installed in c:\SvInstallDir, and uses myces.ini at the location specified.

set SERVERPATH=c:\SvInstallDir
set CESDYNAMIC=c:\ces\myces.ini

The following example binds the application (built with dynamic binding enabled) to Enterprise Server installed in c:\SvInstallDir using the specified path, and uses ces.ini, located in the bin or bin64 directory of c:\SvInstallDir.

set SERVERPATH=c:\SvInstallDir
set CESDYNAMIC=ces.ini

The following example, for any native COBOL application, locates the specified licensing configuration file in the same directory as the application.

set CESDYNAMIC=myces.ini

The following example binds the application (built with dynamic binding enabled) to Enterprise Server using the binary files located in the rt-files sub-directory of the application's working directory.

set BINPATH=\rt-files
Parent topic: Run-time Launch Configuration Files
Related reference
Run-time Launch Configuration File Options


Writing Your Own Setup Program

Note: The following applies to native COBOL only.

You can write your own setup program for applications that run under a COBOL run-time system, such as Enterprise Server. Setting up an application that runs under Enterprise Server requires that the application is deployed to Enterprise Server, but there are no other major considerations.

When you provide your own setup program for an application that uses a COBOL run-time system without Enterprise Server, first you need to decide how your end users will install your application. Will they install your application together with its own run-time system or will they install your application separately from the run-time system, so that the run-time system can be shared with other applications?

The main ways of packaging an application and Enterprise Serverwithout Enterprise Server are:

  • As a standalone application, statically linked to the run-time system. This requires your executable file, the Microsoft Visual C++ run-time system msvcrt.dll and the Enterprise Server licensing files.

    You need to create an installation procedure that:

    1. Installs the Enterprise Server licensing files in the same directory as your application.
    2. Sets up a license database if this is the first time an application using Enterprise Server is being installed on this machine. Subsequent installations use the same license database, so that the database holds a pool of licenses for all the uses of Enterprise Server on the machine.
    3. Installs and starts the license manager service.
  • As an application using a shared run-time system - This run-time system is used by multiple COBOL applications on an end user's machine. It is installed in its own directory, separate from any applications. There is only one run-time system installed on the machine.

    You use the supplied setup program to install a shared Enterprise Server and to set up the relevant registry entries.

  • As an application using its own application-specific run-time system - This run-time system is installed with and is used by a sole COBOL application.

    We recommend installing the full Enterprise Server without Enterprise Server. However for backward compatibility, you can still select the run-time files to install, some of which are mandatory, such as the licensing files.

    You create an installation procedure that installs your application and, in the same directory, installs Enterprise Server (or the selected run-time files). Your installation procedure also needs to set up licensing.

Parent topic: Deploying Native COBOL Applications


To set up an application with a shared Enterprise Server

Note: The following applies to native COBOL only.
  1. Install Enterprise Server.
  2. Install your application executable files in a separate directory from Enterprise Server.
  3. If your application is linked with dynamic binding to the run-time system, create a shortcut pointing to the application. We recommend a shortcut in preference to adding the Enterprise Server directory to the user's path, so that you avoid interactions with other COBOL applications.

    If your application is not linked with dynamic binding, set the PATH on the end-users' machines to point to Enterprise Server, using the following command:

    path = app-server-dir;%PATH%

    where r:\app-server-dir is the directory where Enterprise Server is installed. If you specify a directory containing spaces, you must use quotes ("") to delimit the data values. For example:

    path = "r:\application directory";%PATH%
Parent topic: Deploying Native COBOL Applications


To set up an application with its own Enterprise Server

Note: The following applies to native COBOL only.
  1. Install Enterprise Server.
  2. Install your application executable files in the same directory as Enterprise Server, or if installing the application executable files in a different directory, ensure the Enterprise Server bin or bin64 directory is on the system PATH, or use a run-time launch configuration file.
  3. Create a shortcut pointing to the application. We recommend a shortcut in preference to adding the application directory to the user's PATH, so that you avoid interactions with other COBOL applications.
Parent topic: Deploying Native COBOL Applications


To run a native COBOL application from a network server

You need to configure the licensing for Enterprise Server when running native COBOL applications from a network server.

Server Side

  1. Install Enterprise Server on the server.
  2. Install the license.
  3. Ensure a run-time launch application file, configured with the CESDYNAMIC option, is deployed in the same directory as the application.
    Note: The CES configuration file must be stored in a shared network location; therefore, we recommend that you store it in the bin or bin64 sub-directory of the Enterprise Server installation directory, as this must also be shared.
  4. Copy msvcr100.dll from the C:\Windows\System32 folder into the bin or bin64 sub-directory in the Enterprise Server installation directory.
  5. Click Start > All Programs > Micro Focus product-name > 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 both the Advanced Configuration and the Micro Focus Licensing System Administration dialog boxes.
  9. From the bin or bin64 sub-directory of the Enterprise Server installation directory, create a network share with read permission for everyone.

Client Side

Run the application.

Parent topic: Deploying Native COBOL Applications
Related tasks
Run-time Launch Configuration Files
Related information
To run a .NET COBOL application from a network server


Enterprise Server

  • To install Enterprise Server (or selected files)
  • Enterprise Server Deployment Toolkit
    Describes the component parts of the Enterprise Server Deployment Toolkit.
Parent topic: Deploying COBOL Applications


To install Enterprise Server (or selected files)

Note: The following applies to native COBOL only.

To install the full Enterprise Server (recommended):

  1. Install Enterprise 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 es_231.exe .

    You can also install Enterprise 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 Enterprise Server install file, which is on your CD. To do this, run the executable file es_231.exe .
  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: Enterprise Server


Enterprise Server Deployment Toolkit

  • Introduction to the Enterprise Server Deployment Toolkit
  • Merge Modules
    Provides background information on merge modules and describes the Deployment Toolkit's support for them.
  • License Manager
    Provides background information on the License Manager files supplied in the Deployment Toolkit.
Parent topic: Enterprise Server


Introduction to the Enterprise Server Deployment Toolkit

The Enterprise Server Deployment Toolkit gives you more flexibility when deciding how to deploy your COBOL-based applications that depend on Enterprise Server.

When you install Enterprise Server, the files making up the Deployment Toolkit are contained in the es_231_deployment_sdk.zip file.

Parent topic: Enterprise Server Deployment Toolkit


Merge Modules

Merge modules provide you with a standard method by which you can deliver shared Windows Installer components and setup logic to your applications.

The Deployment Toolkit includes a merge module (.msm file) which you can merge into an application’s Windows installer package (.msi) file to make available all of the Enterprise Server components. It also includes a merge module for the Microsoft Visual C++ Runtime, which is a prerequisite of Enterprise Server.

The names of the supplied merge modules are different for 32-bit and 64-bit Windows systems.

For 32-bit Windows systems they are:

  • enterpriseserver_231x86.msm - the Enterprise Server merge module
  • Microsoft_VC110_CRT_x86.msm

For 64-bit Windows systems they are:

  • enterpriseserver_231x64.msm
  • Microsoft_VC110_CRT_x64.msm

See MSDN for more information on merge modules.

Parent topic: Enterprise Server Deployment Toolkit


License Manager

The Deployment Toolkit includes .msi files to enable you to install the Micro Focus License Manager to work alongside Enterprise Server and your installed application.

The file to use on 32-bit Windows systems is lmsetupx86.msi while for 64-bit Windows systems the file is lmsetupx64.msi.

Example Commands to Install the License Manager

The following examples all use the lmsetupx86.msi file. If you need to install the License Manager onto a 64-bit Windows system, change instances of lmsetupx86.msi to lmsetupx64.msi.

To install License Manager with SafeNet (the default):

start /wait msiexec /i lmsetupx86.msi

To silently install License Manager with SafeNet (the default):

start /wait msiexec /qn /i lmsetupx86.msi

To install License Manager without SafeNet:

start /wait msiexec /i lmsetupx86.msi NOSAFENET=1

To silently install License Manager without SafeNet:

start /wait msiexec /qn /i lmsetupx86.msi NOSAFENET=1
Parent topic: Enterprise Server Deployment Toolkit


Deploying COBOL Applications to the .NET Environment

  • Overview of Deploying COBOL Applications to the .NET Environment
  • Deploying to the .NET Environment with or without a Setup Project
  • Deploying Web and ASP.NET Applications
  • To deploy a Windows application to the .NET environment
  • To deploy a Web Application to the .NET environment
  • To deploy a COBOL Web site to the .NET environment
  • To deploy a CICS service interface to the .NET environment
  • To run a .NET COBOL application from a network server
    You can deploy a .NET managed COBOL application on a network server so that all workstations that are mapped to the server can run the application without the need to install Enterprise Server locally on each workstation.
Parent topic: Deploying COBOL Applications


Overview of Deploying COBOL Applications to the .NET Environment

Managed COBOL applications require Enterprise Server to enable them to run. Enterprise Server provides support for managed COBOL and also for native COBOL. The native COBOL support enables your application to interoperate with native COBOL.

Before you deploy your application, you must first install Enterprise Server.

When you install Enterprise Server, both the native and the managed support is installed. The installation process adds the managed code support files to the Global Assembly Cache (GAC), as well as installing the files into the Enterprise Server directory.

You can deploy COBOL applications using a setup project, or you can copy the files manually. You can also deploy ASP.NET applications using the Publish Web Site tool in Visual Studio.

Parent topic: Deploying COBOL Applications to the .NET Environment
Related information
To deploy a Web Application to the .NET environment
To deploy a Windows application to the .NET environment


Deploying to the .NET Environment with or without a Setup Project

Note: The following applies to COBOL for .NET only.

There are broadly two ways of deploying COBOL Windows-based applications to the .NET environment. You can either use a traditional Setup using Windows Installer technology, or you can copy the files manually. In both cases you need the prerequisite software such as Enterprise Server and the .NET Framework installed on the target machine. See Overview for more information.

With Windows Installer deployment, you package the application in a setup.exe file and distribute that file to users, who run it to install the application.

To create a setup project, you create a new project of the type Setup. This creates a setup.exe program and a Microsoft Installer file (.msi) that encapsulates the entire setup. See the Visual Studio Help.

Alternatively, you can deploy your COBOL application without a setup project. To do this, use the Xcopy command (which copies a directory structure) to copy your application files from the project output directory to the directory containing your installation.

Parent topic: Deploying COBOL Applications to the .NET Environment


Deploying Web and ASP.NET Applications

Note: The following applies to COBOL for .NET only.

Visual Studio provides tools for deploying applications to a Web server. These tools provide an advantage over simply copying files, in that they handle any issues with registration and configuration automatically. However, you can copy the files and register them manually.

Micro Focus COBOL applications deployed to environment such as ASP.NET/Network drives are currently required to have full trust. Applications that are executed without full trust will cause a SecurityException and terminate. Full trust can be configured by using web.config (for ASP.NET) or by using your machines .NET Framework Configuration utility.

Because of the inherent risks that come with running in Full trust mode Microsoft recommends that the ASP.NET applications are isolated. This means that every Web site using COBOL should uses its own application pool and its own application pool identity to cut down the security exposure of executing the application with full trust.

For more information, see the MSDN:

  • How To: Use Code Access Security in ASP.NET 2.0
  • Configuring Security Policy Using the Code Access Security Policy Tool (Caspol.exe)
  • ASP.NET 2.0 Hosting Deployment Guide
Parent topic: Deploying COBOL Applications to the .NET Environment
Related information
To deploy a CICS service interface to the .NET environment
To deploy a COBOL Web site to the .NET environment


To deploy a Windows application to the .NET environment

We recommend that you use a Windows setup project to deploy a Windows application, as follows:

  1. Click File > New > Project.
  2. Expand Other Project Types and choose Setup and Deployment >Setup Project.
  3. Fill in the rest of the details as required.

    See the Visual Studio Help for details.

Alternatively, you can deploy your COBOL application without a setup project, as follows:

  1. Use the Xcopy command (which copies a directory structure) to copy your application files from the project output directory to the directory containing your Micro Focus Server installation.
Parent topic: Deploying COBOL Applications to the .NET Environment


To deploy a Web Application to the .NET environment

We recommend that you use Visual Studio to publish COBOL Web Applications, as follows:

  1. Select the Web Application project in Solution Explorer.
  2. Click Build > Publish WebApplication and specify publish details and credentials as needed. See the Visual Studio Help for details.
Parent topic: Deploying COBOL Applications to the .NET Environment


To deploy a COBOL Web site to the .NET environment

We recommend that you use Visual Studio to publish COBOL Web sites, as follows:

  1. Click Build > Publish Web Site and specify the target location. See the Visual Studio Help for details.

Alternatively, you can deploy a COBOL Web site manually, as follows:

  1. Create a folder on the deployment machine to contain the Web site.
  2. Copy the files in the Web Site folder and its subfolders to the new location.

    If you cannot copy the files because of a "file is in use" error, you need to stop IIS and restart it. Then you should be able to copy the files.

  3. Execute the application from the new location.
Parent topic: Deploying COBOL Applications to the .NET Environment
Related information
Deploying Web and ASP.NET Applications


To deploy a CICS service interface to the .NET environment

  1. Create a folder on the deployment machine to contain the Web site.

    If you used the Service Interfaces feature generate a Web Forms client for a CICS service interface, the name of the folder must be the project name, and it must be located in \inetpub\wwwroot. For example, c:\inetpub\wwwroot\esbank where esbank is the project name.

  2. Copy the files in the Web Site folder and its subfolders to the new location.

    If you cannot copy the files because of a "file is in use" error, you need to stop IIS and restart it. Then you should be able to copy the files.

  3. Update the system path to point to IISpath\projectname\bin

    Where:

    • IISpath is the path to IIS on the deployment machine
    • projectname is the name of the project
  4. Register the file ProxyWrapper.dll, using commands such as:
    cd IISpath\projectname\bin
regsvr32.exe servicenameProxyWrapper.dll

    Where servicename is the name of the generated service.

  5. Execute the application from the new location.
Note: To redeploy, you need to repeat the above process, except that you do not need to update the system path again.
Parent topic: Deploying COBOL Applications to the .NET Environment
Related information
Deploying Web and ASP.NET Applications
Deploying COBOL Applications to the .NET Environment


To run a .NET COBOL application from a network server

You can deploy a .NET managed COBOL application on a network server so that all workstations that are mapped to the server can run the application without the need to install Enterprise Server locally on each workstation.

Before you can configure your .NET COBOL application, ensure that:

  • Enterprise Server is installed and licensed on the server.
  • The workstations that are accessing the server on the network have the necessary permissions.

If your application also uses native code components, you need to setup the licensing and create some shared folders - see To run a native COBOL application from a network server.

Note: The following folders in the installation of Enterprise Server on the server include:
  • %ProgramFiles(x86)%\Micro Focus\Enterprise Server\bin contains the native run-time files for 32-bit machines
  • %ProgramFiles(x86)%\Micro Focus\Enterprise Server\bin64 contains the native run-time files for 64-bit machines
  • %ProgramFiles(x86)%\Micro Focus\Enterprise Server\redist\v4.0 contains the .NET Framework version 4.0 of run-time assemblies
  • %ProgramFiles(x86)%\Micro Focus\Enterprise Server\redist\v2.0 contains the .NET Framework version 2.0 of run-time assemblies

Locating the .NET assemblies

When running a .NET COBOL application from a network server, you need to ensure the appropriate .NET run-time assemblies are available to the application.

The mechanism for locating and loading .NET assemblies at run-time is different to the one used for native .dlls. Native applications use the PATH system environment variable to locate dependent assemblies. For .NET COBOL applications, the required COBOL run-time assemblies must be in the same folder that contains your application files in order for the application to locate them. To ensure this:

  1. Either copy the appropriate run-time assemblies from the redist\v4.0 or redist\v2.0 folders in the Enterprise Server installation location into your application folder, or copy your application files into the appropriate redist\* folder in the Enterprise Server installation location.
  2. Create a network share for the folder that contains your application files and the COBOL run-time assemblies, then make the network share available to your workstations.

    For example, share %ProgramFiles(x86)%\Micro Focus\Enterprise Server\redist\v4.0 if you copied the application to it. If your application targets .NET Framework v2.0, then share the \redist\v2.0 folder.

This approach is not applicable to the scenario where your application uses the standard COBOL CALL mechanism to load the dependent assemblies - for example: set <procedure-pointer> to entry "progname" or call "progname". Programs loaded in this way are located using the PATH environment variable. To make deployment easier, Micro Focus recommends that you keep all dependent .NET assemblies within the same folder.

If you are setting the PATH environment variable to locate any called assemblies in this case, Micro Focus recommends you set the variable directly in your app.config file and not at system level. For example, your app.config file should look like this:

<configuration>
  <configSections>
    <!--The following code declares a section group for application configuration -->
    <sectionGroup name="MicroFocus.COBOL.Application">
      <section name="Switches" type="System.Configuration.NameValueSectionHandler" />
      <section name="Environment" type="System.Configuration.NameValueSectionHandler" />
    </sectionGroup>
    <!--The following code declares a section group for run-time configuration -->
    <sectionGroup name="MicroFocus.COBOL.Runtime">
      <section name="Tunables" type="System.Configuration.NameValueSectionHandler" />
      <section name="Switches" type="System.Configuration.NameValueSectionHandler" />
    </sectionGroup>
  </configSections>
  <MicroFocus.COBOL.Application>
    <Switches />
    <Environment>
      <add key="PATH" value="F:\myappfiles;%PATH%" />
    </Environment>
  </MicroFocus.COBOL.Application>
</configuration>

Network security considerations

By default, network drives only have "local intranet" permissions which restricts a lot of the operations you might want to do on them. This is why, when running a .NET COBOL application from a network share, you need to elevate its security level. You can do this in one of the following ways:

  • Add an app.config file to the application which includes the following code that provides full trust to assemblies on the network share:
    <runtime>
    <loadFromRemoteSources enabled="true"/>
</runtime>

    For example:

    <?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <!--The following code declares a section group for application configuration -->
    <sectionGroup name="MicroFocus.COBOL.Application">
      <section name="Switches" type="System.Configuration.NameValueSectionHandler" />
      <section name="Environment" type="System.Configuration.NameValueSectionHandler" />
    </sectionGroup>
    <!--The following code declares a section group for run-time configuration -->
    <sectionGroup name="MicroFocus.COBOL.Runtime">
      <section name="Tunables" type="System.Configuration.NameValueSectionHandler" />
      <section name="Switches" type="System.Configuration.NameValueSectionHandler" />
    </sectionGroup>
  </configSections>
  <runtime>
      <!--The following line provides Full Trust for assemblies loaded from a network share -->
      <loadFromRemoteSources enabled="true"/>
   </runtime>
</configuration>
  • Alternatively, use Microsoft's caspol (Code Access Security Policy) tool on the share that contains your application. See Microsof's MSDN for more information about how to do this.
Parent topic: Deploying COBOL Applications to the .NET Environment
Related tasks
Run-time Launch Configuration Files


Enterprise Server

  • Enterprise Server configuration and administration
    Describes the processes for setting up, configuring, and maintaining an Enterprise Server installation. The information it contains relates to both COBOL applications running as services, and mainframe subsystems 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.
  • Reference for MSS Deployment
    Contains information on general and CICS commands, data conversion, resource definitions, and supplied transactions.
  • Enterprise Server Security
    Contains information and procedures for all aspects of securing an Enterprise Server installation.
  • Enterprise Server License Messages
Parent topic: Micro Focus Enterprise Server 2.3 Update 1 for Windows


Enterprise Server configuration and administration

Describes the processes for setting up, configuring, and maintaining an Enterprise Server installation. The information it contains relates to both COBOL applications running as services, and mainframe subsystems that operate in an Enterprise Server environment.
  • Overview and Architecture
  • Configuration and Administration User Interface
  • Planning your Configuration
  • Configuring the Server Instance Environment
  • Configuring and Administering Enterprise Server Instances
  • Enterprise Server Clustering
  • SSL Support for CICS Web Interface Servers
  • User Certificate Registration for CICS Web Interface Servers
  • Configuring Client-Server Communications
  • Configuring Enterprise Server for IBM WebSphere MQ
    This topic details the steps you need to take to configure IBM WebSphere MQ.
  • Monitoring Enterprise Server
  • User Exits for Request Handlers
  • Troubleshooting
  • Enterprise Server Administration Console Help Pages
Parent topic: Enterprise Server


Overview and Architecture

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

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.

  • CICS regions

    In an Enterprise Server environment, a CICS region can operate as an enterprise server instance. These CICS regions behave in the same manner as those operating in a mainframe CICS environment. You can configure a CICS region operating as an enterprise server instance to communicate with a CICS region running on a mainframe.

  • IMS applications

    You can configure an enterprise server instance to run IMS applications.

  • JCL jobs

    You can configure an enterprise server instance to run batch initiator and batch printer JCL jobs.

Parent topic: Overview and Architecture


Enterprise Server Architecture

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. For example, in an Enterprise Server CICS implementation, a CICS region runs as an enterprise server instance.

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

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

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

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

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 C:\Users\All Users\Micro Focus\Enterprise Developer\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)

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

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

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

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

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

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

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
  • Handles CICS Interval Control Processing
  • Monitors region state for timeouts and deadlocks
  • Dispatches JCL jobs to initiators
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:

  • CICS Channels and Containers support
  • Historical Statistics Facility
  • Auxiliary trace logging
  • CICS journal control
  • CICS extra-partition transient data processing
  • 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 following service listeners:

  • TN3270
  • CICS ISC
  • Web Services

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

CASDBC - IMS Database Control

CASDBC is responsible for IMS DB support and is an optional component with one for every region. It is started by CASCD.

CASTMC - IMS Transaction Manager Control
CASTMC is responsible for IMS TM support, and is an optional component with one for every region. It is started by CASCD.
Parent topic: Overview and Architecture


Configuration and Administration User Interface

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

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

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

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

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.

You can also access Enterprise Server Administration from the Start menu. The option varies depending on the Micro Focus product you are using. For example, for Enterprise Developer, you can choose the following option: Start > All Programs > Micro Focus Enterprise Developer > Configuration > Enterprise Server Administration

If you have Enterprise Developer installed, there are two alternative methods of accessing Enterprise Server Administration on your local machine:
  • Click Start > All Programs > Micro Focus Enterprise Developer > Configuration > Enterprise Server for .NET 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
  • Securing the Repository Files
    Details the steps you need to take to prevent unauthorized access to the repository files.
Parent topic: Configuration and Administration User Interface
Parent topic: Enterprise Server Task Index


Displaying Server Information

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

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


Securing the Repository Files

In most installations, the information maintained by the Micro Focus Directory Server (MFDS), also known as the repository, is kept in a series of files on the local filesystem. (It is also possible to keep the repository in an LDAP server.) These files can contain sensitive data, so if non-administrative users have access to the system where MFDS is running, the system administrator needs to take steps to secure these files.

The location of the files is displayed in the MFDS user interface. To discover this location, click Options from the menu on the left, and then click the Repository tab.

You should set ACLs (Windows) or permissions (UNIX) on the repository files and directories so that they can be read and modified by the user account under which the MFDS process runs, but not by non-privileged users.

Parent topic: Accessing the Enterprise Server Administration UI


Planning your Configuration

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

  • Introduction
  • Security Options
  • Enterprise Server Execution Control Under Windows
  • Firewall configuration
  • About Communications Processes
  • Deployment Services and Listeners
  • Enterprise Server Instance Configuration Issues
  • Performance Considerations
Parent topic: Enterprise Server configuration and administration


Introduction

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

  1. Decide on a user account strategy and implement it.
  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

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

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, MSS applications 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.

User ID and password constraints

Enterprise Server emulates the mainframe operating system on Microsoft Windows, UNIX and Linux operating system platforms. Mainframe user authentication constraints and technical limitations are therefore emulated through the Enterprise Server External Security Facility (ESF) Manager to ensure mainframe compatibility.

These constraints and technical limitations apply to many components of Enterprise Server including:
  • CICS
  • Job Entry Subsystem (JES)
  • Micro Focus Directory Server (MFDS)
  • IMS
User IDs and passwords are limited to a maximum of eight ASCII characters.

To avoid issues with user signon and similar functions, avoid attempting to create user IDs or passwords that do not meet these requirements.

Parent topic: Security Options
Parent topic: Architecture and Overview


Enterprise Server Execution Control Under Windows

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.

Parent topic: Planning your Configuration
Related information
Defining Enterprise Server Instance Administrators


Firewall configuration

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 for most platforms, 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: Windows XP is not officially supported. If you are, however, 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

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

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

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:

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 c:\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 %ProgramFiles(x86)%\Micro Focus\Enterprise Server\bin and modify it as necessary.

For example, if Enterprise Server is installed in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer, then "<ES>/deploy" becomes %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\deploy.

Parent topic: Deployment Services and Listeners


Deployment Listeners

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin and \bin64 .

On Windows platforms, the special token "<ES>" is translated into the installation directory. For example, if Enterprise Server is installed as part of Enterprise Developer in the default installation directory, then "<ES>/deploy" becomes %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\deploy.

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>=c:/web
 docs=c:/web/documents
 images=d:/media/images

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

Parent topic: Deployment Services and Listeners


Enterprise Server Instance Configuration Issues

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

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 Enterprise 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

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

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

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

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

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

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

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

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, such as DDNAMEs, 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 configure a setting that allows you to access and run JCL files from the local machine. For example, if you are managing a Unix enterprise server from a Windows machine, you can access and run JCL files stored on the local Windows machine.

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
  • Reserved Environment Variables
  • About Communications Processes
  • Configuring Fileshare
  • Using XA-compliant Resources (XARs)
Parent topic: Enterprise Server configuration and administration


Configuring Environment Variables

You can use Enterprise Server environment variables to configure many server instance environment properties. This section contains information on setting environment variables, and on the environment variables that are available.

Tip: This section contains an alphabetical listing of environment variables, and environment variables listed by functional group. For variable values, check the alphabetical listing, and if this does not contain values, search the online help for the variable name.
  • 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

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 semi-colon to separate elements within the string. For example:

[ES-Environment]
COBPATH=c:\adirectory;c:\anotherdirectory
Note: Micro Focus recommends that you do not set the COBDIR environment variable for an enterprise server instance. 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=d:\data
FILEA=$FILEROOT\mydata.dat

This resolves to d:\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

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

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 Windows, from a command shell you can use the net start command to start MFDS. However, environment variables set in the current command shell’s environment are inherited by the net.exe command, but they are NOT inherited by the MFDS service.

The net start command sends a message to the Windows service controller requesting that it start MFDS. The service controller starts the mfds.exe process, and MFDS inherits its environment.

To change the environment for the MFDS Windows service process, you need to change the system environment on the machine on which the service runs, for example using the System control panel, or by editing it in the Registry.

After you have made the changes, reboot the machine so that the Service Manager configures the new environment.

Parent topic: Setting Environment Variables


To Set Environment Variables from the User Interface

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

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:

set 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

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

    For example, you could create an environment variable named PRODDATA and set its value to d:\mydataset.

    Then, to allocate a dataset in the catalog for a file named MFIO1.SAMPLE.DATA, you would use this code:

     //*MFE:%PCDSN='$PRODDATA\MFI01.SAMPLE.DATA'
Parent topic: Setting Environment Variables


Environment Variables by Groups

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.
  • CICS-Specific Environment Variables
  • Enterprise Server Communications Environment Variables
    Environment variables for configuring the input and output and the display.
  • File Handling and Dataset Environment Variables
  • IMS-Specific Environment Variables
  • Input, output and display environment variables
  • JCL-specific environment variables
  • Mainframe Access Environment Variables
  • WebSphere MQ-Specific Environment Variables
  • PL/I-Specific 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.
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.

  • /D
    Logs the contents of all buffers passed to and from the CCI functions. The default condition for this option is OFF.
    Warning: This type of tracing may not produce the desired results if the application has been coded to prohibit data tracing.
  • /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


CICS-Specific Environment Variables

These environment variables relate to configuring the CICS environment.

Note: The Environment variables in alphabetical order topic contains the values for most environment variables.
Variable | Description
CICS_SIT | The name of the SIT used by the region
ES_CICS_SINGLE | Configures CICS so that a user can only log on once
ES_CLASS_XPCT | Overrides the default CICS PCT resource class
ES_CLASS_XCMD | Overrides the default CICS CMD resource class
ES_CLASS_XDCT | Overrides the default CICS DCT resource class
ES_CLASS_XFCT | Overrides the default CICS FCT resource class
ES_CLASS_XJCT | Overrides the default CICS JCT resource class
ES_CLASS_XPPT | Overrides the default CICS PPT resource class
ES_CLASS_XPSB | Overrides the default CICS PSB resource class
ES_CLASS_XRES | Overrides the default CICS DOCTEMPLATE resource class
ES_CLASS_XTST | Overrides the default CICS TST resource class
ES_CLASS_XTRAN | Overrides the default CICS TRAN resource class
ES_DISABLE_DFLTUSR_SIGNON | Disables the default user ("mfuser") signon when invoking ES Monitor & Control.
ES_ECI_MAX_RESP | Specifies the maximum expected response size (in bytes) to use when using Micro Focus ECI support to invoke CICS programs.
ES_ESM_CMDSEC | Indicates whether CICS processing honors the CMDSEC option specified on a transaction's PLT definition
ES_ESM_PLTPIUSR | The user id under which PLT programs run during CICS initialization
ES_ESM_RESSEC | Indicates whether CICS processing honors the RLS security setting specified on a transaction definition (PCT)
ES_ESM_SECPRFX | Indicates whether CICS processing prefixes the resource names when making security queries
ES_ESM_XUSER | Indicates whether CICS processing performs surrogate user checks
ES_EUSA_SIZE | Sets the size of the extended user storage area, allowing large memory allocations to be set using the GETMAIN SHARED command. Set this variable to a numeric value representing the number of MB.
ES_EZASOKET_SUPPORT | Switches on EZASOKET support
ES_INQFILE_RETURN | Modifies EXEC CICS INQUIRE FILE behavior
ES_JES_FREE_SSTM_SYSOUT | When set to Y, decreases the amount of memory used when processing CICS spool datasets in an SSTM enterprise server.
ES_LE370_SUPPORT | Enables support for Language Environment (LE) in CICS applications
ES_MQ_1PC | Indicates whether the WebSphere MQ switch module ESMQXA should operate in one-phase commit mode. Set this environment variable only when advised to do so by Micro Focus.
ES_MQ_LIB The full name including the path of the IBM WebSphere MQ client or server library.
Important: In AIX environments the library is an object inside a shared object. For example
ES_MQ_LIB="/usr/mqm/lib64/libmqmxa64.a(libmqm64.o)"
ES_MQ_LIB_T | The full name including the path of the IBM WebSphere MQ client or server library, for threaded environments
ES_MQ_LIB_XA The full name including the path of the IBM WebSphere 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 WebSphere MQ XA library, for threaded environments
ES_MQ_XA | Specifies whether the two-phase commit protocol uses a static or dynamic XA structure
ES_PLI_SUPPORT | Tells the CICS Emulation that it needs to load its subsystem support for PL/I user programs. The default value is "N".
ES_SSTM_CICS | Location of the JCL used to initialize the SSTM CICS environment
ES_SURROGATE_JOB_USER | Associates a user ID with a job when submitting the job for processing through the internal reader from CICS
ES_USR_DFLT_CICS | Allows you to override the default user when no user is logged on for CICS authentication
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.
ES_xxxxx_NB_RETRIES | Specifies the number of times a SEP attempts to reconnect to an XA resource following a connection error, where xxxxx is the ID of the associated resource. The default is 5. If no connection is made, the XA switch is disabled.
TXTRANP | The location of the CICS application object files.
Parent topic: Environment Variables by Groups
Related reference
Environment variables in alphabetical order


Enterprise Server Communications Environment Variables

Environment variables for 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
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 Micro Focus ECI instead of IBM CTG
ES_MAX_CATALOG_LINES | Restricts the number of entries displayed in ESMAC catalog view, and the default is 5000
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_TN3270_FORCE_ALT | Enables you to use a screen size other than the default when using a TN3270 terminal emulator
ES_TN3270_MODEL_LOG | Writes the TN3270 emulator's model name to a temporary storage queue named TN32MODL that can be viewed using the CEBR transaction
ES_USR_DFLT_CICS | Allows you to override the default user when no user is logged on for CICS authentication
ES_USR_DFLT_ESMAC | Allows you to override the default user when no user is logged on for ESMAC authentication
ES_USR_DFLT_JES | Allows you to override the default user when no user is logged on for JES authentication
ES_ESM_DISABLE_DFLTUSER_ESMAC | Allows you to disable the default ESMAC user in order to increase the security of your server. Disables the DEFAULT button on the logon screen and forces users to always enter a valid userid and password.
ES_WS_RUNAWAY_TIMEOUT | Time in seconds that the client will wait for a response from the web service. Valid values are 0 to 65535 seconds.
IMSCPY | The location of copybook files for the DBDGEN, MFSGEN, and PSBGEN utilities.
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 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
MQSERVER | The location of an WebSphere MQ Server installation.
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
TERM | Specifies terminal type
TERMINFO | Locates the UNIX system terminfo database
TMPDIR | Locates the directory for temporary files
TX_TN3270_FORCE_ALT | Enables you to use a screen size other than the default when using a TN3270 terminal emulator
TXMAPP | The location of the BMS load module
TXRDTP | The location of MSS resource definition (RDO) files.
USER | Default user name
Parent topic: Environment Variables by Groups


File Handling and Dataset Environment Variables

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 one or more locations, separated by ; (Windows) or : (UNIX), in which to search for data files at run time. As long as the file assignment does not contain a sub-path (that is, a string containing \ or /) then the file assignment is appended to each location specified by COBDATA in order to locate the file. Note: Users modernizing RM/COBOL or ACUCOBOL-GT legacy code can use a sub-path in the file assignment, but only by compiling with the relevant DIALECT or IDXFORMAT values for the respective File Handling systems; setting these values in the File Handling configuration file is not sufficient to achieve this.
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
GDG.RECALL | Controls the recall of HSM archived datasets when accessing mainframe GDGs using MFA Data Access Services
HCOBND | A directory for DB2 bind files
LIB | The location of the DB2 LIB directory
MFALLOC_LOC | The location of the default allocated dataset
MFALLOC_PROP | Rules for generated PC dataset names on allocation (that is, the default catalog PC DSN format)
MF_NEWSPACE | Indicates whether SPACE is required for NEW datasets
MF_SYSLOGDSN | The Syslog Dataset name
MFLOCKING | Enables Locking Support
PROCLIB | Specifies PROCLIB datasets. This can be a concatenation of PDS names.
STRICTVSAM | When set to ON and under a mainframe emulation, a file status of 37 is returned when you open an existing VSAM file for OUTPUT and the file has or previously had some data written to it, or if the file format is different from the file on disk. The default for this variable is OFF.
TXFILEP | The location of Micro Focus VSAM files
Parent topic: Environment Variables by Groups


IMS-Specific Environment Variables

This topic lists environment variables relate to configuring the IMS environment.

Note: The Environment Variables: Alphabetical Order topic contains the values for most environment variables.
Variable | Description
ES_ACBLIB | The location of IMS ACB files.
ES_DFS3650 | The default transaction to execute or MOD file to be displayed after successfully signing on to IMS. You specify these by setting environment variables prior to the start of the region: ES_DFS3650 - set to MOD if a MOD file is to be sent, or TRX if a TRANSACTION is to be executed. If you set to MOD, ES_MOD3650 needs to be set to the name of the MOD you want to display. If you set to TRX, ES_TRX3650 needs to be set to the name of the transaction.
ES_IMS_CONFIG | The IMS TM parameters.
ES_IMS_DB_COMMIT_FLUSH | When set to 0 (zero), forces the flushing of database buffers to disk on CLOSE only (default). When set to 1, forces the flushing of database buffers to disk on COMMIT only.
ES_IMS_DB_TLOG_WRITETHRU | When set to 0 (zero), forces the flushing of TLOG buffers to disk on COMMIT only (default). When set to 1, forces the flushing of TLOG buffers to disk on all database I/O.
ES_IMS_DEADLOCK_WAIT | Time in milliseconds to wait before checking for a deadlock. The default is 1000 (1 second).
ES_IMS_DIAGNOSE | Marks IMS TM as diagnose mode only for IMSMSGQ.
ES_IMS_DOSVS_PCB | Emulates DOS/VSE PCB address alignment for EXEC DLI programs.
ES_IMS_DUMP_ON_DEADLOCK | Creates a system dump when a deadlock is detected.
ES_IMS_DUMP_ON_TIMEOUT | Creates a system dump when a lock timeout occurs.
ES_IMS_EXITPATH | The location of compiled code that contains segment and/or field exits.
ES_IMS_FORCE_SIGNON | Enables a user to force a sign-on to IMS on the current terminal and sign off from other terminals.
ES_IMS_IBMPLATFORM Sets the emulation for the IMS run-time. Valid values are: M (for MVS) or D (for DOSVS). The default value is M.
Note: This variable is rarely required to be changed from its default, even for the majority of DOSVS users.
ES_IMS_IMSID | Allows the user to specify the IMS System ID returned to the AIBTDLI INQY ENVIRON call.
ES_IMS_INQY_OTMA | Returns TPIPE, MBR, SYNC, and MSYNC to an INQY call.
ES_IMS_INQY_UNKNOWN | Value returned to an INQY call.
ES_IMS_IRLM | Enables Internal Lock Resource Manager (IRLM) locking. IRLM locking more closely parallels mainframe IMS database DB locking behavior, reducing data constraint and potential for deadlock.
ES_IMS_LOCALDLI | Deprecated. See IMS Database Locking. When set to 1, directs batch program execution to process all IMS DB calls entirely in the JES initiator providing significant performance improvement. All IMS DB control processes accessed from the batch program must be stopped before execution because they become exclusively owned by JES until the program completes.
ES_IMS_LOCK_TIMEOUT | The number of seconds during which IMS DB control continues to retry a locked record before timing out. Valid values are 0 to 65535. The default is 30 seconds; a value of 0 indicates an indefinite wait time.
ES_IMS_LU_LTERM | Determines the value of the LTERM literal returned by the MFS system. Valid values are: Y to return the LU name; N to return the user ID.
ES_IMS_MESGQ | Sets the configuration for the IMS TM message queue. See ES_IMS_MESGQ in Environment variables in alphabetical order for details.
ES_IMS_PATH | The location of compiled COBOL applications.
ES_IMS_PLI_INDIRECT_PCBADDR

Determines whether the PL/I program converts the PCB address list from a direct to an indirect addressing technique. Set the variable to one of the following values:

D
If the main program is a PL/I program, PCB addresses are converted from a direct to an indirect addressing technique.
Y
Always converts addresses from a direct to an indirect addressing technique as long as the PSB language is set to PL/I.
N
Never converts addresses from a direct to an indirect addressing technique.

The default is D (dynamic).

ES_IMS_RCLASS

Creates a set of newly-named IMS security resource classes, appending the variable's value (maximum of seven characters) to each resource class' default character.

Create theses custom-named classes if you are using the same ESM active directory with two Enterprise Server systems and your security needs to differ for each.

See Resource Classes for IMS Security for the names of the resource classes created if this variable is not set.

ES_IMS_RELEASE | Allows the user to specify the IMS Release returned to the AIBTDLI INQY ENVIRON call.
ES_IMS_REGION | Allows the user to specify the IMS Region returned to the AIBTDLI INQY ENVIRON call.
ES_IMS_ROLLBACK | Enables automatic Backward Recovery; enabled by default.
ES_IMS_ROLLFORWARD | Enables or disables Forward Recovery logging. Valid values are: Y to enable; N to disable. The default is N.
ES_IMS_SPARSE_EXIT_LANG
Indicates the language of the IMS DB secondary index sparse routines. Set the variable to one of the following values:
  • C (for COBOL)
  • A (for Assembler)
By default, this variable is not set (sparse exits are disabled).
ES_IMS_SUPPORT | Enables IMS support.
ES_IMS_TLOG_COMPRESS | When set to 0 (zero), disables compression of the Backward Recovery TLOG file. When not compressed, the file contains only the information required to recover databases. The default is enabled.
ES_IMS_TLOG_FLUSH When set to 1, forces the frequent flushing of TLOG and database buffers to disk.
Note: This environment variable is deprecated. Use ES_IMS_DB_TLOG_WRITETHRU to flush TLOG buffers and ES_IMS_DB_COMMIT_FLUSH to flush database buffers.
ES_IMS_TLOG_MAXSIZE | Maximum size of the IMS DB transaction logging file in bytes. The default is 4GB or h"FFF00000".
ES_IMS_TLOG_PATH | The location of IMS DB transaction logging files. The default is the Enterprise Server system directory.
ES_IMS_TLOG_THRESHOLD | Threshold size of the IMS DB transaction logging file. When reached, the current TLOG file is closed and a new TLOG file created for subsequent transactions. The default is 2GB or h"7FFFFFFF".
ES_IMS_LOCK_RETRY_DELAY | The IMS DB lock retry delay in milliseconds.
ES_IMSCFG | The location of the IMS configuration files IMSCONFG.DAT. This is reserved for future use.
ES_IMSDAT | The location of IMS DB data files.
ES_IMSLIB | The location of DBDGEN2.DAT, DBDGEN2F.DAT and PSBGEN3.DAT files.
ES_MFSLIB | The location of the control blocks generated by the MFS generation program.
ES_MOD3650 | The default MOD file to be displayed after a successful sign-on to IMS. See ES_DFS3650.
ES_SSTM_IMS | Location of the JCL used to initialize the SSTM IMS environment.
ES_TRX3650 | The default transaction to run after a successful sign-on to IMS. See ES_DFS3650.
ES_TMC_AGGREGATE | Controls the performance environment for IMS TM data stores. See ES_TMC_AGGREGATE in Environment variables in alphabetical order for details.
ES_USR_DFLT_IMS | Allows you to override the default user when no user is logged on for IMS authentication.
ICONN1 | Controls the client TCP connection status of an IMS Connect emulator.
IMSCPY | The location of copybook files for DBDGEN, PSBGEN and MFSGEN utilities .
MFIMS_ACBDUMP_TIMESTAMP | Suppresses date/time stamp display in ACB report.
MFIMS_BMPCHKP | Returns a QC to a checkpoint call when it the call includes an IO area.
MFIMS_BTS | Configures Mainframe Express-format BTS tracing
MFIMS_DIBSTAT_CODES | Specifies additional DIBSTAT return codes to be returned to EXEC DLI program.
MFIMS_DLI_OPT | Specifies DL/I call optimization flags.
MFIMS_DIAG | Enables IMS BTS format diagnostic tracing.
MFIMS_FLUSHTRACE | Flushes BTS trace file to disk after every write.
MFIMS_FP_DA | Bypasses keycheck on IMS Fastpath DB delete.
MFIMS_LOADMVS | Disables load of MVS support for IMS application programs.
MFIMS_PCBCALL | Allows a standalone EXEC DLI program to issue a PCB call.
Parent topic: Environment Variables by Groups
Parent topic: IMS Support in Enterprise Server
Related concepts
Dynamic IMS Message Queue Performance Tuning
TLOG Files
Enabling IRLM Locking
Deadlocking
Related tasks
To enable dynamic IMS message queue performance tuning
To dynamically tune IMS message queue performance
To dynamically adjust the IMS message queue configuration
Related reference
Environment variables in alphabetical order


Input, output and display environment variables

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_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_JES_SPOOL_ORDER | The order in which the spool list is displayed when you first open ESMAC. The default spool order is ascending. Setting this environment variable to 1 changes it to descending order - any other value displays it in ascending order.
ES_LEGACY_ECI | Indicates that Enterprise Server must use Micro Focus ECI instead of IBM CTG
ES_MAX_CATALOG_LINES | Restricts the number of entries displayed in ESMAC catalog view, and the default is 5000
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_TN3270_FORCE_ALT | Enables you to use a screen size other than the default when using a TN3270 terminal emulator
ES_TN3270_MODEL_LOG | Writes the TN3270 emulator's model name to a temporary storage queue named TN32MODL that can be viewed using the CEBR transaction
ES_USR_DFLT_CICS | Allows you to override the default user when no user is logged on for CICS authentication
ES_USR_DFLT_ESMAC | Allows you to override the default user when no user is logged on for ESMAC authentication
ES_USR_DFLT_JES | Allows you to override the default user when no user is logged on for JES authentication
ES_ESM_DISABLE_DFLTUSER_ESMAC | Allows you to disable the default ESMAC user in order to increase the security of your server. Disables the DEFAULT button on the logon screen and forces users to always enter a valid userid and password.
IMSCPY | The location of copybook files for the DBDGEN, MFSGEN, and PSBGEN utilities.
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 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
MQSERVER | The location of a WebSphere MQ Server installation.
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
TERM | Specifies terminal type
TERMINFO | Locates the UNIX system terminfo database
TMPDIR | Locates the directory for temporary files
TX_TN3270_FORCE_ALT | Enables you to use a screen size other than the default when using a TN3270 terminal emulator
TXMAPP | The location of the BMS load module
TXRDTP | The location of MSS resource definition (RDO) files.
USER | Default user name
Parent topic: Environment Variables by Groups


JCL-specific environment variables

This topic lists environment variables relate to configuring the JCL environment.

Variable Description
CASRDO44_NEWSUB Enables access to JCL files held on the local machine on which the browser is running.
CASRDO44_NEWSUB=Y|N
CASSPOOL_LOCK_RETRY_COUNT If errors are experienced by the spool module, the number of times it retries to obtain a record lock can be adjusted using this environment variable. The default value is 20.
CASSPOOL_LOCK_RETRY_COUNT=num-retries
ES_ALLOC_EXPAND The default value is Y, which expands an environment variable when used to specify an allocation path. Set to N to override this behavior, which is to not expand the variable used in the path.
ES_ALLOC_EXPAND=Y|N
ES_ALLOC_OVERRIDE The location of a file containing rules that determine where new data sets are created. This applies only to JES and batch files, and not CICS, IMS, or Web services files.
ES_ALLOC_OVERRIDE=rules-file
ES_JESYSMSG_OUTPUT Routes the system messages spool files (JESYSMSG) from batch jobs directly to the Enterprise Server Output queue, rather than the Out Hold queue.
ES_JESYSMSG_OUTPUT=Y|N
ES_JESYSMSG_RESTRICTED When system message spool files are being routed directly to the Output queue, by using ES_JESYSMSG_OUTPUT, you can hold back spool files based on their class, by using ES_JESYSMSG_RESTRICTED.
ES_JESYSMSG_RESTRICTED=class-name/number

To specify multiple class names or numbers, enter them as a string; for example, ABC123 for classes A, B, C, 1, 2, & 3.

ES_JES_BYTES Maximum number of bytes to output in a job before taking the action specified (either cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message).
ES_JES_BYTES=num-bytes
ES_JES_CARDS Maximum number of cards to output in a job before taking the action specified (either cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message).
ES_JES_CARDS=num-cards
ES_JES_DISABLE_RESTART_FLUSH Indicates whether a region's jobs are moved from the Active queue to the Output Hold queue when a region is restarted.
ES_JES_DISABLE_RESTART_FLUSH=Y|N
ES_JES_LEVEL Sets the default JCL type.
ES_JES_LEVEL=JES2|JES3|VSE
ES_JES_LINES Maximum number of lines to output in a job before taking the action specified (either cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message).
ES_JES_LINES=num-lines
ES_JES_OUTLIM Maximum number of lines to output to a particular data set before calling the user exit, processing any global limits, and then cancelling the job.
ES_JES_OUTLIM=num-lines
ES_JES_PAGES Maximum number of pages to output in a job before taking the action specified (either cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message).
ES_JES_PAGES=num-pages
ES_JES_RESTART Enables JCL restart processing.
ES_JES_RESTART=Y|N
ES_JES_SPOOL_ORDER The order in which the spool list is displayed when you first open ESMAC.
ES_JES_SPOOL_ORDER=1|any
1
Spool list displayed in descending order.
any
Any value other than 1 displays the spool list in ascending order. This is the default.
ES_PL1_MFFH_JCL Enables you to run Open PL/I programs that access JCL data definitions. The default value is N.
ES_PL1_MFFH_JCL=Y|N
ES_SAM_ESDS Under VSE, when this is set to Y, opening an OUTPUT of a reusable ESDS file resets the file when the DISP is not specified in the DLBL statement.
ES_SAM_ESDS=Y|N
ES_SSTM_CICS Location of the JCL used to initialize the SSTM CICS environment.
ES_SSTM_CICS=file-location
ES_SSTM_IMS Location of the JCL used to initialize the SSTM IMS environment.
ES_SSTM_IMS=file-location
ES_SSTM_JOB_FLUSH_ACTIVE By default, this is set to N.

When set to Y, causes a CICS SSTM job to be removed from the ACTIVE queue when the region shuts down.

ES_SYSOUT_HOLD Sysout held classes.
ES_SYSOUT_HOLD=???
ES_USR_DFLT_JES Allows you to override the default user when no user is logged on for JES authentication.
ES_USR_DFLT_JES=Y|N???
JES_PRINT_SPOOL_MSG Specifies the disposition of the spool data set printing message (JES000029I).
JES_PRINT_SPOOL_MSG=CONSOLE|LOG|SILENT
CONSOLE
The console.log file (default).
LOG
A special log file named PRNT_SPL_MSG_YYYY_MM_DD.DAT where YYYY_MM_DD is the current date. This file resides in the same directory as casspool.dat, and a new file is created every day.
SILENT
No messages. Use this option with caution, as you will have no audit log of your spool data sets.
Note: This environment variable is introduced for high print load users, where print messages to the console impact system performance.
MFALLOC_PCFILE When set to Y, which is the default, it will cause a catalogued file to be created if DSORG=PS is provided in the DCB parameters.
MFALLOC_PCFILE=Y|N
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.

An entry shorter than 8 characters must have trailing spaces extending its length to 8 characters.

MF_ALIAS=program-name1 alias1
[program-name2 alias2]
...[program-name10 alias10]
MF_CHARSET Specifies which character set an enterprise server is to use.
MF_CHARSET=A|E|ASCII|EBCDIC

The default value is ASCII.

MF_DUPJOBS Enables jobs with identical names to run.
MF_DUPJOBS=Y|N

The default value is N.

MF_FALLTHRUCHECK Specifies that MSS is to check that the main COBOL program ends by executing a GOBACK or STOP RUN.
MF_FALLTHRUCHECK=Y|N

The default value is Y.

MF_JESPWR_EXIT Used to pass JES2 and VSE PWR statements to the user exit MFJESPWR. If this environment variable is set, the JCL execution engine will call the exit program, MFJESPWR, whenever a JES2 or VSE PWR statement is encountered. It passes the contents of the JCL record plus Job and Job Step information. A sample MFJESPWR.cbl is included with the product.
MF_JESPWR_EXIT= Y|N

The default value is N.

MF_JCL_AUDIT Specifies that the audit log records audit information when a catalog entry is deleted.
MF_JCL_AUDIT=DELT|DELJ|DELT,DELJ
DLET
Logs audit information each time an ESMAC/CAS utility deletes a catalog entry.
DLEJ
Logs audit information each time a step in a JCL job deletes a catalog entry.
DLET,DLEJ
Logs audit information each time either an ESMAC/CAS utility or a JCL job step deletes a catalog entry.

The default is that this is not set.

MF_MFA Specifies what data set catalogs are to be searched.
MF_MFA=ALL|RJSE
  • ALL - Search for data sets first in the local catalog, and if not found, on the mainframe (default).
  • RJSE - Search for data sets in the local catalog only. No mainframe is performed.
MFJ_REPRO_EMPTY Enables or disables the ability for the IDCAMS REPRO action to copy from a pristine VSAM file.
MFJ_REPRO_EMPTY=Y|N

When set to Y, the resulting file will be empty.

The default value is N, which will produce a JCLAM0150S error when attempted.

MFJSENGINE

Specifies which sort engine the utility MFJSORT is to emulate.

MFJSENGINE=DFSORT|SYNCSORT

The default value is DFSORT.

MF_MVSJOB
Sets the number at which a job starts and finishes.
MF_MVSJOB=<lower value>{-|+}<upper value>
Where:
<lower value>
Number at which a job starts. Contains 5 digits - for example, 00001
-
Sets the values but only on the first startup of the region.
+
Reset the values to these new ones.
<upper value>
Upper job number. Contains 5 digits - for example, 99999
For example:
set MF_MVSJOB=00010+00100
This resets the values to start with job number 10 and run through to job number 100. When the upper limit has been reached you receive a message:
All job numbers in the range 00010:00100 are in use
At this point you need to remove some jobs from the spool - you can use the spool housekeeping functions to do this.
MF_NODD Specifies what action MSS is to take at run time if a job step uses a file that has not been allocated.
MF_NODD=A|R
A
Abend the program. This is the default.
R
Returns file status 3/5.
MF_PCRENAME_LAX

When an MVS data set is renamed, the associated physical file is normally renamed only if it is in the Default Allocation data set location.

MF_PCRENAME_LAX=Y|N
Y
Enable physical files in other locations to be renamed if the cataloged name is changed.
N
Only physical files in the default allocation data set location are renamed. This is the default value.
MF_RCCF Enables Remote Job Step Execution (RJSE).
MF_RCCF=DELETEJOB|KEEPJOB
MF_SMS Enables support for SMS data classes. SMS is IBM's Storage Management Subsystem. MSS provides emulation for SMS data classes only. To enable DATACLAS support this variable needs to be set ON in addition to setting MFUSERCAT_NODE=SYSMFE1.
MF_SMS=ON|OFF

The default value is OFF.

MF_SPOOL_HK_TESTDATE Overrides the normal date for the spool housekeeping.
MF_SPOOL_HK_TESTDATE=YYYYMMDD
MF_UCC11
Note: This environment variable works independently of the JCL RESTART parameter.
Enables emulation of UCC11, a third party add-on to the mainframe that affects data set disposition processing. If UCC11 is enabled, a data set disposition of NEW is accepted even if the data set already exists.
MF_UCC11=Y|N|M
Y
JCL job re-start functionality is enabled. When restarting a job with DISP=(NEW,CATLG), it will not result in job failure due to the data set already being cataloged.
M
On restart, a catalogued data set is presumed to have an initial disposition of MOD rather than NEW. As a result, any new data is appended to the existing data set.
N
JCL job re-start functionality is disabled. This is the default value.
MF_USESCA7 Specifies that MSS accepts CA7 Scheduler control statements as comments rather than diagnosing them as errors. CA7 Scheduler control statements begin with # in column 1.
MF_USESCA7=ON|OFF

The default value is OFF.

MFJ_INPUTDS_ERROR When set to N, will cause IEBDG, IEBGENER and IEBCOMPR to treat missing input files as thought they were present but empty.
MFJ_INPUTDS_ERROR=Y|N
MFREXX_CHARSET Specifies the character set used by the REXX engine when working with hexadecimal strings or performing string comparisons.
MFREXX_CHARSET=A|E
A
ASCII. This is the default value.
E
EBCDIC.
MFREXX_CONCAT Specifies one or more characters to be used for the CONCAT operator in addition to REXX's default, which is "||".
MFREXX_CONCAT=char-spec

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.

Any error in the specification of the additional characters, including the specification of alphabetic or numeric characters, results in the environment variable being ignored.

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.
MFREXX_LSEQ_RECSIZE_MAX=rec-length
rec-length
Record length to use. The minimum value you can specify is 255. Specifying an invalid value, or a value less than 255, results in the default value (255) being used.
MFREXX_NOT Specifies one or more characters to be used for the NOT operator in addition to REXX's default, which is "¬".
MFREXX_NOT=char-spec
char-spec
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.
Any error in the specification of the additional characters, including the specification of alphabetic or numeric characters, results in the environment variable being ignored.
MFREXX_OR One or more characters to be used for the OR operator in addition to REXX's default, which is "|".
MFREXX_OR=char-spec
char-spec
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.
Any error in the specification of the additional characters, including the specification of alphabetic or numeric characters, results in the environment variable being ignored.
MFSYSCAT The location of the JES system catalog.
MFSYSCAT=cat-file
cat-file
The fully-qualified location and name of the system catalog file to use.
MFUSERCAT_LOC The location of the user catalog.
MFUSERCAT_LOC=definition-file
definition-file
The fully-qualified location and name of the data class definition file to use.
MFUSERCAT_NODE Sets node to enable DATACLAS support. Must be used in conjunction with MF_SMS=ON.
MFUSERCAT_NODE=SYSMFE1

This is not set by default.

VSE_STARTUP_CFG The location of the VSE JCL configuration file.
VSE_STARTUP_CFG=config-file
config-file
The fully-qualified location and name of the configuration file to use.
Parent topic: Environment Variables by Groups
Related reference
JOB Statement Extensions


Mainframe Access Environment Variables

These environment variables relate to the Mainframe Access functionality.

AUTOCAT_IMP
Name of an input file name for automated catalog import using MFA Data Access Services.
Values
  • An input file path and name.
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
COBCPY
Specifies the directory or directories that the Compiler and Animator should search for copyfiles.
Values
  • A list of search directories, each item separated by a semicolon.
DBG_MVSPSKEL
The skeleton JCL for debugging
ENTRYNAMEMAP
Location of the mfentmap.dat entry name map file.
Values
  • File path and name of the mfentmap.dat entry name map file.
GDG.RECALL
Controls the recall of HSM archived datasets when accessing mainframe GDGs using MFA Data Access Services.
HELP
The location of IBM PL/I help files
HOST_DISP
Determines whether JCL DISP will be honored for DELETE on mainframe resident datasets.
HOST_NEW
Determines whether JCL looks on the host for new datasets that are not cataloged locally.
MF_SET_USERID
Sets the default user ID.
MAINFRAME_FLOATING_POINT
Specifies the format to use for floating point data items.
Values
  • true specifies that IBM hexadecimal format floating point data items are to be used.
  • false specifies that IEEE format floating point data items are to be used.
Note:
  • Setting MAINFRAME_FLOATING_POINT to anything other than true has the same effect as setting it to false.
  • The setting of this environment variable can be overridden by the NATIVE-FLOATING-POINT directive.
MFACLIENTINI
The complete path to the INI file containing mainframe logon credentials, which defaults to:

c:\users\USERNAME\appdata\roaming\micro focus\mfaclient.ini

MFAIMBEDDEDHEX
Indicates that you wish to have all source code embedded hex values handled in the same way as the MDECONV application, in that all translated hex values less than x'1f' will have a null character inserted before the hex value. The COBOL run-time system will properly handle these imbedded hex values. Example:
SET MFAIMBEDDEDHEX=COBOL
MFAMAXHOTLINKS
If using the hot-link software from Micro Focus, the LSC applications will route all communication request through this hot-link. The hot-link remains active to the mainframe until you shut down your workstation, or enter the command MFDAELSC CLOSE. The hot-link is able to allocate and load balance more than multiple simultaneous links and will start up an additional link if any request has to wait for more than 15 seconds for a time slice. The maximum number of simultaneous links can be specified, with a default of 4 and a maximum of 10, as follows:
SET MFAMAXHOTLINKS=4
MFAMAXSENDLENGTH
Sets the maximum length of data, in a single communication packet, that can be transmitted to or from the mainframe. This does not affect the size of the file that can be transmitted, but only the size of each of the numerous data chunks that are transmitted to make up the entire file. This is only useful, when there is a router that limits the transfer length of data to or from the mainframe, or there is a restriction in the length of data that can be transferred. Example:
SET MFAMAXSENDLENGTH=4000
MFASERV
Controls how mainframe access checks for a dataset name (DSN):
  • ON

    If a DSN is not found in the local catalog, then the catalog API calls MFA to check the mainframe for the DSN.

  • Not set

    The catalog API does not call MFA to check the mainframe for the DSN.

MFE.FALLTHRUCHECK
Enables messages to be issued if the user program does not return from a main program via GOBAK or STOP RUN.
MFUSERCAT_NODE
User catalog node
MVSCATIO_TIMEOUT
Time allowed for a catalog input/output operation to complete
NEWJCL
Controls ISPF skeleton JCL processing
SHOW_CATALOG_WAIT
Displays a message when the enterprise server is waiting for a response from the catalog server.
Parent topic: Environment Variables by Groups


WebSphere MQ-Specific Environment Variables

These environment variables relate to configuring the WebSphere MQ environment. For the most part, you do not need to specify these environment variables, unless you have installed WebSphere MQ in a non-default location, or you are instructed to do so by Micro Focus.

ES_MQ_1PC
Indicates whether the IBM WebSphere MQ switch module ESMQXA should operate in one-phase commit mode. Set this environment variable only when advised to do so by Micro Focus.
ES_MQ_LIB
The full name including the path of the IBM WebSphere MQ client or server library
Important: In AIX environments the library is an object inside a shared object. For example
ES_MQ_LIB="/usr/mqm/lib64/libmqmxa64.a(libmqm64.o)"
ES_MQ_LIB_T
The full name including the path of the IBM WebSphere MQ client or server library, for threaded environments
ES_MQ_LIB_XA
The full name including the path of the IBM WebSphere MQ XA library
Important: In AIX environments the library is an object inside a shared object. For example
ES_MQ_LIB="/usr/mqm/lib64/libmqmxa64.a(libmqm64.o)"
ES_MQ_LIB_XA_T
The full name including the path of the IBM WebSphere MQ XA library, for threaded environments
ES_MQ_LISTENER
Defines one or more WebSphere MQ listeners.
Values
ES_MQ_LISTENER={QueueManagerName,QueueName,ListenerName}
[,QueueManagerName,QueueName,ListenerName]...
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
MQSERVER
The name of a minimal channel.
Values
MQSERVER=ChannelName/TransportType/MachineName(Port)
where:
  • ChannelName specifies the name of a channel as defined on the server
  • TransportType specifies the communications protocol, which can be:
    • TCP
    • LU62
    • NETBIOS
    • SPX
  • MachineName(Port) specifies the name of the server machine and optional port number
Example:
MQSERVER=CHANNEL3/TCP/QServer(1414)
Important: If you have defined MQ as an XA resource, then the values used in this environment variable must also be contained in the XA open string. See XAR for WebSphere MQ for more information.

This environment variable is IBM-defined, and more information may be found in the relevant IBM publication.

Parent topic: Environment Variables by Groups
Parent topic: Configuring Enterprise Server for IBM WebSphere MQ
Related information
XAR for WebSphere MQ
XA Resource Manager Definition for WebSphere MQ


PL/I-Specific Environment Variables

This topic lists environment variables relate to configuring the PL/I environment.

Note: The Environment Variables: Alphabetical Order topic contains the values for most environment variables.
Variable | Description
ES_IMS_PLI_INDIRECT_PCBADDR

Determines whether the PL/I program converts the PCB address list from a direct to an indirect addressing technique. Set the variable to one of the following:

D
If the main program is a PL/I program, PCB addresses are converted from a direct to an indirect addressing technique.
Y
Always converts address as long as the PSB language is PL/I.
N
Never converts addresses.

The default is D (which stands for dynamic).

ES_PL1_MFFH | Enables Micro Focus File Handler to perform all Open PL/I I/O operations. The default value is "Y". If it is set to "N", then all I/O will be routed to old Liant file handlers.
ES_PL1_MFFH_JCL | Enables you to run Open PL/I programs that access JCL data definitions. The default value is "N".
ES_PLI_SUPPORT | Tells the CICS Emulation that it needs to load its subsystem support for PL/I user programs. The default value is "N".
IBM_DBG_LANG | The language the IBM PL/I debugger should use
MFPLI_PRODUCT_DIR | The location of the Open PL/I installation. It is used to find files needed for compiling and linking.
Parent topic: Environment Variables by Groups


Security and Auditing Environment Variables

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
ES_CESN_NO_OS390 | Use this variable to override the default behaviour CESN transaction response for invalid user credentials. Default behaviour reports "Your userid is invalid" or "Your password is invalid". Setting this variable to any value will cause CESN to produce an invalid credential message instead.
ES_DISABLE_DFLTUSR_SIGNON | Disables the default user ("mfuser") signon when invoking ES Monitor & Control.
ES_ESM_PLTPISEC | The level of security checking for PLTPI processing
ES_ESM_RCF | Determines how RACF is used for command authorization
ES_OLD_SEC_TSTD | Prevents security being enforced for TS or TD queues that are not declared in the security repository.
ES_SURROGATE_JOB_USER | Associates a user ID with a job when submitting the job for processing through the internal reader from CICS.
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

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

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.
DBG_MVSPSKEL | The skeleton JCL for debugging
ES_DDBG_PORT_RANGE | A range of ports to use for dynamic debugging
MFTRACE_ANNOTATIONS | The location of the Enterprise Developer 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
TX_MQTRACE | Enables tracing in dfh0mqis for WebSphere MQ calls
Parent topic: Environment Variables by Groups


Reserved Environment Variables

CAUTION:
These variables are for Micro Focus use only and must not be set unless advised to do so by Micro Focus SupportLine.
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_HOME | ES_IDEBIN
ES_IMS_TRACE | ES_LOAD_SWITCH_PLUS | ES_LOG_PERF_EVENTS
ES_MNM_SUPPORT | 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 | LIBLIST | MAX_POOL_THREAD_CASDBC
MAX_POOL_THREAD_CASGATE | MAX_POOL_THREAD_CASMQB | MAX_POOL_THREAD_CASTMC
MAX_POOL_THREAD_CASTRC | MAX_POOL_THREAD_CASTSC | 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 | XFHNODE
XFH2BTR |  |
  • MAX_POOL_THREAD_CASDBC
    Sets the maximum number of pool threads for CASDBC.
  • MAX_POOL_THREAD_CASGATE
    Sets the maximum number of pool threads for CASGATE.
  • MAX_POOL_THREAD_CASMQB
    Sets the maximum number of pool threads for CASMQB.
  • MAX_POOL_THREAD_CASTMC
    Sets the maximum number of pool threads for CASTMC.
  • MAX_POOL_THREAD_CASTRC
    Sets the maximum number of pool threads for CASTRC.
  • MAX_POOL_THREAD_CASTSC
    Sets the maximum number of pool threads for CASTSC.
Parent topic: Environment Variables by Groups
Parent topic: Configuring the Server Instance Environment


Environment variables in alphabetical order

C

CASRDO44_NEWSUB
Category: General
Enables access to JCL files held on the local machine on which the browser is running.
Values
  • ON

    Access JCL files on the local machine on which the browser is running.

  • OFF

    Access JCL files from the machine running the enterprise server.

CASSPOOL_LOCK_RETRY_COUNT
Category: JES
If errors are experienced by the spool module, the number of times it retries to obtain a record lock can be adjusted using this environment variable.
Values
  • The number of retries made to obtain a record lock.
  • Default: 20
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.

CICS_SIT
The name of the SIT used by the region.
Values
  • The name of the SIT that the region uses.
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 one or more locations, separated by ; (Windows) or : (UNIX), in which to search for data files at run time. As long as the file assignment does not contain a sub-path (that is, a string containing \ or /) then the file assignment is appended to each location specified by COBDATA in order to locate the file.
Note: Users modernizing RM/COBOL or ACUCOBOL-GT legacy code can use a sub-path in the file assignment, but only by compiling with the relevant DIALECT or IDXFORMAT values for the respective File Handling systems; setting these values in the File Handling configuration file is not sufficient to achieve this.
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.
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_ACBLIB
The location of IMS ACB files.
Values
  • The path location of the IMS ACB files.
ES_ALLOC_EXPAND
The default value is Y, which expands an environment variable when used to specify an allocation path. Set to N to override this behavior, which is to not expand the variable used in the path.
Values
  • Y/N.
ES_ALLOC_OVERRIDE
The default value is Y, which expands an environment variable when used to specify an allocation path. Set to N to override this behavior, which is to not expand the variable used in the path.
Values
  • File path and name of the dataset rules file.
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_CICS_SINGLE
Configures CICS so that a user can only log on once.
Values
  • Y A user can only log on once.
  • Not set: A user can log on multiple times. This is the default.
ES_CLASS_XPCT
Overrides the default CICS PCT resource class
Values
  • Yes
  • No
  • The overriding class. The default is: ACICSPCT
ES_CLASS_XCMD
Overrides the default CICS CMD resource class
Values
  • Yes
  • No
  • The overriding class. The default is: CCICSCMD
ES_CLASS_XDCT
Values
  • Yes
  • No
  • The overriding class. The default is: DCICSDCT
Overrides the default CICS DCT resource class
ES_CLASS_XFCT
Overrides the default CICS FCT resource class
Values
  • Yes
  • No
  • The overriding class. The default is: FCICSFCT
ES_CLASS_XJCT
Overrides the default CICS JCT resource class
Values
  • Yes
  • No
  • The overriding class. The default is: JCICSJCT
ES_CLASS_XPPT
Overrides the default CICS PPT resource class
Values
  • Yes
  • No
  • The overriding class. The default is: MCICSPPT
ES_CLASS_XPSB
Overrides the default CICS PSB resource class
Values
  • Yes
  • No
  • The overriding class. The default is: PCICSPSB
ES_CLASS_XRES
Overrides the default CICS DOCTEMPLATE resource class
Values
  • Yes
  • No
  • The overriding class.
ES_CLASS_XTST
Overrides the default CICS TST resource class
Values
  • Yes
  • No
  • The overriding class. The default is: SCICSTST
ES_CLASS_XTRAN
Overrides the default CICS TRAN resource class
Values
  • Yes
  • No
  • The overriding class. The default is: TCICSTRN
ES_CLUSTER
Identifies a region as participating in an Enterprise Server Cluster. Mandatory for all regions in a cluster.
Values
  • Any value sets the variable.
ES_CLUSTER_LISTENER_PORT_TO_USE
Value: port-number
This variable enables you to use a specific port for a listener of the cluster.
ES_CLUSTER_ISC_TRACE
Enables tracing on the Enterprise Server Cluster ISC listeners.
Values
  • Any value sets the variable.
ES_CONSOLE_LOG
Sends console messages to the Windows Event Log
Values
  • Yes Console messages are sent to the Windows Event Log
ES_CSKL_NO_MSG_CONSOLE
Stops CSKL writing messages to console.log
Values
  • Yes CSKL messages are not written to the console log.
ES_DDBG_PORT_RANGE
A range of ports to use for dynamic debugging
You specify a range of port numbers separated by a hyphen or a comma; the second port number must be greater than the first.
Example: ES_DDBG_PORT_RANGE=8001-8040
ES_DISABLE_DFLTUSR_SIGNON
Disables the default user ("mfuser") signon when invoking ES Monitor & Control (ESMAC).
Values
  • Y or y Having logged on to ES administration via your MFDS internal security account, you no longer receive the auto logon as "mfuser" when accessing ESMAC.
ES_DFS3650
The default transaction to execute or MOD file to be displayed after successfully signing on to IMS. You specify these by setting environment variables prior to the start of the region: ES_DFS3650 - set to MOD if a MOD file is to be sent, or TRX if a TRANSACTION is to be executed. If you set to MOD, ES_MOD3650 needs to be set to the name of the MOD you want to display. If you set to TRX, ES_TRX3650 needs to be set to the name of the transaction.
ES_ECI_MAX_RESP
Specifies the maximum expected response size (in bytes) to use when using Micro Focus ECI support to invoke CICS programs. You need to use this environment variable when the amount of data returned from the CICS programs is approximately more than twice the size of the input data, which is sometimes the case when using channels and containers where the back-end program creates or enlarges containers.
ES_ESM_CMDSEC
Indicates whether CICS processing honors the CMDSEC option specified on a transaction's PLT definition.
Values
  • ASIS

    CICS honors the CMDSEC option defined in a transaction's resource definition. CICS calls its command security checking routine only when CMDSEC(YES) is specified in a transaction resource definition.

  • ALWAYS

    CICS overrides the CMDSEC option, and always calls its command security checking routine to issue the appropriate call to the SAF interface.

ES_ESM_IDPW_CASE
Forces the case of user ID and password for single attempt ESM authentication. You use the environment variable with a format ES_ESM_IDPW_CASE=xy, where "x" is the folding option for user ID, and "y" the option for password.
The settings for "x" and "y" are:
  • U - Always uppercase.
  • L - Always lowercase.
  • M - Mixed case and case sensitive

Example: ES_ESM_IDPW_CASE=UM - a single authentication is tried with the user ID folded to uppercase, and the password used as-is.

ES_ESM_PLTPISEC
The level of security checking for PLTPI processing.
Values
  • NONE

    You do not want any security checking on PLT initialization programs.

  • CMDSEC

    You want CICS to perform command security checking only.

  • RESSEC

    You want CICS to perform resource security checking only.

  • ALL

    You want CICS to perform both command and resource security checking.

ES_ESM_PLTPIUSR
The user id under which PLT programs run during CICS initialization.
Values
  • The userid that CICS is to use for security checking for PLT programs that run during CICS initialization.
ES_ESM_RCF
Determines how RACF is used for command authorization
Values:
  • A Includes options T, C, and S.
  • C Specifies that RACF is to be used for ETO terminal command authorization.
  • N Specifies that no sign-on, transaction, or command authorization is to be performed by RACF.
  • S Specifies that RACF is to be used for static and ETO terminal command authorization. Includes option C.
  • T Specifies that RACF is to be used for sign-on and transaction authorization.
  • Y Includes options T and C.
ES_ESM_RESSEC
Indicates whether CICS processing honors the RLS security setting specified on a transaction definition (PCT).
Values:
  • ASIS

    The RLS security setting of a transaction will be honored. That is, resource level security checking is performed only when the RLS security checkbox is marked in the PCT definition.

  • ALWAYS

    CICS processing always performs resource level security checking irrespective of the RLS security setting on the transaction definition.

ES_ESM_SECPRFX
Indicates whether CICS processing prefixes the resource names when making security queries.
Values
  • NO

    No prefixes are used

  • YES

    Resource names are prefixed with the CICS region user ID.

  • <prefix>

    A string to be used as the prefix for resource names. It can be 1 to 8 upper case alphanumeric characters and it must start with an alphabetic character.

ES_ESM_XUSER
Indicates whether CICS processing performs surrogate user checks.
Values
  • NO

    No surrogate user checking is performed.

  • YES

    Perform surrogate user checking wherever such checks are permitted.

ES_ESMAC_DISP_MAX_OVERRIDE
Limits the number of lines shown when viewing the individual catalog entry.
Values
  • An integer number of the ESMAC catalog view lines to display.
ES_EUSA_SIZE
Sets the size of the extended user storage area, allowing large memory allocations to be set using the GETMAIN SHARED command. Set this variable to a numeric value representing the number of MB.
ES_GLM
If this variable is set, it identifies the region as an Enterprise Server Cluster Global Lock Manager (GLM).
Values
  • Any value sets the variable.
ES_GLM_TIMEOUT
The duration in which a submit request to an Enterprise Server Cluster Global Lock Manager (GLM) can be retried before disabling the connection permanently.
Values
  • n seconds.

This variable only applies to the region within an Enterprise Server Cluster designated as the GLM.

ES_HOSTNAME_TO_USE
In an Enterprise Server Cluster, if a machine uses more than one network card, you may need to set this variable to indicate which hostname MFCS should use.
Values
  • The relevant hostname.
ES_JES_FREE_SSTM_SYSOUT
When set to Y, decreases the amount of memory used when processing CICS spool datasets in an SSTM enterprise server.
ES_IMS_CONFIG
The IMS TM parameters.
ES_IMS_DB_COMMIT_FLUSH
When set to 0 (zero), forces the flushing of database buffers to disk on CLOSE only (default). When set to 1, forces the flushing of database buffers to disk on COMMIT only.
ES_IMS_DB_TLOG_WRITETHRU
When set to 0 (zero), forces the flushing of TLOG buffers to disk on COMMIT only (default). When set to 1, forces the flushing of TLOG buffers to disk on all database I/O.
ES_IMS_DEADLOCK_WAIT
Time in milliseconds to wait before checking for a deadlock. The default is 1000 (1 second).
ES_IMS_DIAGNOSE
Marks IMS TM as diagnose mode only for IMSMSGQ.
Values
  • Y The Transaction Manager (TM) works in diagnostic mode only, and no activity key points are written to the message queue. Use this feature only when advised to do so by Micro Focus.
ES_IMS_DOSVS_PCB
Emulates DOS/VSE PCB address alignment for EXEC DLI programs.
ES_IMS_DUMP_ON_DEADLOCK
Creates a system dump when a deadlock is detected.
ES_IMS_DUMP_ON_TIMEOUT
Creates a system dump when a lock timeout occurs.
ES_IMS_EXITPATH
The location of compiled code that contains segment and/or field exits.
ES_IMS_FORCE_SIGNON
Enables a user to force a sign-on to IMS on the current terminal and sign off from other terminals.
ES_IMS_IBMPLATFORM
Sets the emulation for the IMS run-time. Valid values are: M (for MVS) or D (for DOSVS). The default value is M.
Note: This variable is rarely required to be changed from its default, even for the majority of DOSVS users.
ES_IMS_IMSID
Allows the user to specify the IMS System ID returned to the AIBTDLI INQY ENVIRON call.
ES_IMS_INQY_OTMA
Returns TPIPE, MBR, SYNC, and MSYNC to an INQY call.
ES_IMS_INQY_UNKNOWN
Value returned to an INQY call.
ES_IMS_LOCALDLI
Deprecated. See IMS Database Locking. When set to 1, directs batch program execution to process all IMS DB calls entirely in the JES initiator providing significant performance improvement. All IMS DB control processes accessed from the batch program must be stopped before execution because they become exclusively owned by JES until the program completes.
ES_IMS_IRLM
Enables Internal Lock Resource Manager (IRLM) locking. IRLM locking more closely parallels mainframe IMS database DB locking behavior, reducing data constraint and potential for deadlock.
ES_IMS_LOCK_TIMEOUT
Allows the user to specify the IMS System ID returned to the AIBTDLI INQY ENVIRON call.
ES_IMS_LOCK_RETRY_DELAY
The IMS DB lock retry delay in milliseconds.
ES_IMS_LU_LTERM
Determines the value of the LTERM literal returned by the MFS system. Valid values are: Y to return the LU name; N to return the user ID.
ES_IMS_MESGQ
Sets the configuration for the IMS TM message queue. The ES_IMS_MESGQ environment variable is generated and set automatically by Enterprise Server, and is reserved.
Restriction: Manually set this variable only when advised to do so by Micro Focus SupportLine.
ES_IMS_MESGQ=[ds-file-name];max-blocks;buffer-count;start-control;[cushion-size]
ds-file-name
An alternative data store file to the default, which is IMSMESGQ.dat.
max-blocks
Data store size limit represented as the number of 64K blocks. Default is 4.
buffer-count
The number of 64K buffers to allocate. Default is 2.
start-control
A flag that sets the start behavior as follows:
Y | Cold start the resource definitions. Default.
S | Cold start the statistics and resource state information.
Q | Cold start the data store (system cold start).
cushion-size
The size of the cushion to be reserved for graceful lack-of-space behavior, represented as a number from 0 to 255. The specified number represents 32 times the actual percentage of max-blocks reserved for emergency use. The default is 4 (a raw value of 128).
ES_IMS_PATH
The location of compiled COBOL applications.
ES_IMS_PLI_INDIRECT_PCBADDR

Determines whether the PL/I program converts the PCB address list from a direct to an indirect addressing technique. Set the variable to one of the following:

D
If the main program is a PL/I program, PCB addresses are converted from a direct to an indirect addressing technique.
Y
Always converts address as long as the PSB language is PL/I.
N
Never converts addresses.

The default is D (which stands for dynamic).

ES_IMS_RELEASE
Allows the user to specify the IMS Release returned to the AIBTDLI INQY ENVIRON call.
ES_IMS_REGION
Allows the user to specify the IMS Region returned to the AIBTDLI INQY ENVIRON call.
ES_IMS_ROLLBACK
Enables automatic Backward Recovery; enabled by default.
ES_IMS_ROLLFORWARD
Enables or disables Forward Recovery logging. Valid values are: Y to enable; N to disable. The default is N.
ES_IMS_SPARSE_EXIT_LANG
Indicates the language of the IMS DB secondary index sparse routines. Set the variable to one of the following values:
  • C (for COBOL)
  • A (for Assembler)
By default, this variable is not set (sparse exits are disabled).
ES_IMS_SUPPORT
Enables IMS support.
ES_IMS_TLOG_COMPRESS
When set to 0 (zero), disables compression of the Backward Recovery TLOG file. When not compressed, the file contains only the information required to recover databases. The default is enabled.
Note: When enabled, Enterprise Server reclaims space in the file when information becomes obsolete.
ES_IMS_TLOG_FLUSH
When set to 1, forces the frequent flushing of TLOG and database buffers to disk.
Warning: Depending upon the number of database updates, the frequency of commits, and other computer activity, use of ES_IMS_TLOG_FLUSH could result in significant performance degradation.
Note: This environment variable is deprecated. Use ES_IMS_DB_TLOG_WRITETHRU to flush TLOG buffers and ES_IMS_DB_COMMIT_FLUSH to flush database buffers.
ES_IMS_TLOG_MAXSIZE
Maximum size of the IMS DB transaction logging file in bytes. The default is 4GB or h"FFF00000".
ES_IMS_TLOG_PATH
The location of IMS DB transaction logging files. The default is the Enterprise Server system directory.
ES_IMS_TLOG_THRESHOLD
Threshold size of the IMS DB transaction logging file. When reached, the current TLOG file is closed and a new TLOG file created for subsequent transactions. The default is 2GB or h"7FFFFFFF".
ES_IMSCFG
The location of the IMS configuration files IMSCONFG.DAT. This is reserved for future use.
ES_IMSDAT
The location of IMS DB data files.
ES_IMSLIB
The location of DBDGEN2.DAT, DBDGEN2F.DAT and PSBGEN3.DAT files.
ES_INQFILE_RETURN
Modifies EXEC CICS INQUIRE FILE behavior.
ES_JESYSMSG_OUTPUT
Routes the system messages spool files (JESYSMSG) from your batch jobs directly to the Enterprise Server Output queue, rather than the Out Hold queue.
Values
  • Y

All job messages will be sent to the Output queue, but will only actually print (either physically or logically) if the MSGCLASS of the job matches one of the sysout classes defined to an active printer.

ES_JES_BYTES
Maximum number of bytes to output in a job before taking the action specified (either cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message)
ES_JES_CARDS
Maximum number of cards to output in a job before taking the action specified (either cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message)
ES_JES_DISABLE_RESTART_FLUSH
Indicates whether a region's jobs are moved from the Active queue to the Output Hold queue when a region is restarted
ES_JES_LEVEL
Sets the default JCL type to JES2, JES3 or VSE
ES_JES_LINES
Maximum number of lines to output in a job before taking the action specified (either cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message)
ES_JES_OUTLIM
Maximum number of lines to output to a particular dataset before calling the user exit, processing any global limits, and then cancelling the job
ES_JES_PAGES
Maximum number of pages to output in a job before taking the action specified (either cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message)
ES_JES_RESTART
Enables JCL restart processing
ES_JES_SPOOL_ORDER
The order in which the spool list is displayed when you first open ESMAC. The default spool order is ascending. Setting this environment variable to 1 changes it to descending order - any other value displays it in ascending order.
ES_LE370_SUPPORT
Enables support for Language Environment (LE) in CICS applications
ES_LEGACY_ECI
Indicates that Enterprise Server must use Micro Focus ECI instead of IBM CTG
ES_MAX_CATALOG_LINES
Restricts the number of entries displayed in ESMAC catalog view, and the default is 5000
ES_MEM_STRATEGY
Selects the types of memory processes supported
ES_MFASM_SUPPORT
Enables Assembler support when running CICS server regions.
Values
  • N

    No Assembler supported for CICS server regions.

  • Y

    Assembler supported for CICS server regions.

ES_MFSLIB
The location of the control blocks generated by the MFS generation program.
ES_MOD3650
The default MOD file to be displayed after a successful sign-on to IMS. See ES_DFS3650.
ES_MQ_1PC
Indicates whether the IBM WebSphere MQ switch module ESMQXA should operate in one-phase commit mode. Set this environment variable only when advised to do so by Micro Focus.
ES_MQ_LIB
The full name including the path of the IBM WebSphere MQ client or server library
Important: In AIX environments the library is an object inside a shared object. For example
ES_MQ_LIB="/usr/mqm/lib64/libmqmxa64.a(libmqm64.o)"
ES_MQ_LIB_T
The full name including the path of the IBM WebSphere MQ client or server library, for threaded environments
ES_MQ_LIB_XA
The full name including the path of the IBM WebSphere MQ XA library
Important: In AIX environments the library is an object inside a shared object. For example
ES_MQ_LIB="/usr/mqm/lib64/libmqmxa64.a(libmqm64.o)"
ES_MQ_LIB_XA_T
The full name including the path of the IBM WebSphere MQ XA library, for threaded environments
ES_MQ_LISTENER
Defines one or more WebSphere MQ listeners.
Values
ES_MQ_LISTENER={QueueManagerName,QueueName,ListenerName}
[,QueueManagerName,QueueName,ListenerName]...
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_NO_CLUSTER
This variable can be set to prevent any attempt by a region to join an Enterprise Server Cluster
Values
  • Any value sets the variable.
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 in seconds that an OTMA client should wait for an answer (default value 120)
ES_PL1_MFFH
Enables Micro Focus File Handler to perform all Open PL/I I/O operations. The default value is "Y". If it is set to "N", then all I/O will be routed to old Liant file handlers.
ES_PL1_MFFH_JCL
Enables you to run Open PL/I programs that access JCL data definitions. The default value is "N".
ES_PLI_SUPPORT
Tells the CICS Emulation that it needs to load its subsystem support for PL/I user programs. The default value is "N".
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_SSTM_CICS
Location of the JCL used to initialize the SSTM CICS environment
ES_SSTM_IMS
Location of the JCL used to initialize the SSTM IMS environment.
ES_SSTM_JOB_FLUSH_ACTIVE
By default, this is set to N. When set to Y, causes a CICS SSTM job to be removed from the ACTIVE queue when the region shuts down.
ES_SURROGATE_JOB_USER
Associates a user ID with a job when submitting the job for processing through the internal reader from CICS.
Values
  • Any value

    The user ID that started the ES region is used in the job submission.

  • No Value

    The CICS default user CICSUSER, or as specified by ES_USR_DFLT_CICS, is used in the job submission.

ES_SYSOUT_HOLD
Sysout held classes
ES_TMC_AGGREGATE
Controls the performance environment for IMS TM data stores.
[ES-Environment]
ES_TMC_AGGREGATE={[,N|,D]|nnn,Y}
,N
Sets the default behavior, which is to unilaterally flush operating system buffers to your physical disk at each key transactional point. While this does not change the method used by default at startup, it does enable dynamic modification via ESMAC. Once set, you can then test the effect of various non-default settings by altering them dynamically.
,D
Disables the transactional flushing of operating system buffers to disk. This option can significantly enhance message queue performance; however it is at the expense of the transactional integrity of the message queue in the event of a system failure.
Note: To avoid unpredictable results when using this setting, we highly recommend that you also set the static options as follows on the Administration Server > Properties > MSS > IMS > TM > General tab:
  • Set Cold start to Everything (queue)
  • Check Persist

See Server Instance Properties: MSS IMS TM General for details.

nnn,Y
Enables the aggregated transactional flushing of operating system buffers to disk where nnn represents an interval of time, in milliseconds, during which additional buffers are allowed to accumulate before flushing. Valid values are 0 through 255.

Once a thread reaches a key transactional point and requests a flush, TM waits the specified interval to accumulate subsequent threads that also request a flush. At the end of the interval, one flush is performed for all accumulated requests thus potentially improving performance by reducing the number of flush commands issued to the operating system.

Note:
  • Threads requesting a flush wait until the flush is confirmed.
  • Generally, when the message queue resides on a higher performance I/O subsystem such as one using SSDs, a smaller value, e.g. 1 or 2, produces the best results. A value of 10 or higher seldom improves performance.
ES_TN3270_FORCE_ALT
Enables you to use a screen size other than the default when using a TN3270 terminal emulator
ES_TN3270_MODEL_LOG
Writes the TN3270 emulator's model name to a temporary storage queue named TN32MODL that can be viewed using the CEBR transaction
ES_TRX3650
The default transaction to run after a successful sign-on to IMS. See ES_DFS3650.
ES_USR_DFLT_CICS
Allows you to override the default user when no user is logged on for CICS authentication
ES_USR_DFLT_ESMAC
Allows you to override the default user when no user is logged on for ESMAC authentication
ES_ESM_DISABLE_DFLTUSER_ESMAC
Allows you to disable the default ESMAC user in order to increase the security of your server. Disables the DEFAULT button on the logon screen and forces users to always enter a valid userid and password.
ES_USR_DFLT_JES
Allows you to override the default user when no user is logged on for JES authentication
ES_USR_DFLT_IMS
Allows you to override the default user when no user is logged on for IMS 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
ES_EZASOKET_SUPPORT
Switches on (value "Y") EZASOKET support
Note: This feature is deprecated. Configuration of EZASOKET is now defined via Enterprise Server Administration.

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

ICONN1
Controls the client TCP connection status of an IMS Connect emulator.
IMSCPY
The location of copybook files for DBDGEN, PSBGEN and MFSGEN utilities .
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 (which uses LIBPATH). 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_FALLTHRUCHECK
Specifies that MSS is to check that the main COBOL program ends by executing a GOBACK or STOP RUN.
Values:
  • y (default)
  • n
MF_JCL_AUDIT
Specifies that the audit log records audit information when a catalog entry is deleted.
Values:
  • DLET - Logs audit information each time an ESMAC/CAS utility deletes a catalog entry
  • DLEJ - Logs audit information each time a step in a JCL job deletes a catalog entry
  • DLET,DLEJ - Logs audit information each time either an ESMAC/CAS utility or a JCL job step deletes a catalog entry
MF_MFA
Specifies what dataset catalogs are to be searched.
Values:
  • ALL - Search for datasets first in the local catalog, and if not found, on the mainframe (default)
  • RJSE - Search for datasets in the local catalog only. No mainframe is performed.
MF_MVSJOB
Sets the number at which a job starts and finishes.
MF_MVSJOB=<lower value>{-|+}<upper value>
Where:
<lower value>
Number at which a job starts. Contains 5 digits - for example, 00001
-
Sets the values but only on the first startup of the region.
+
Reset the values to these new ones.
<upper value>
Upper job number. Contains 5 digits - for example, 99999
For example:
set MF_MVSJOB=00010+00100
This resets the values to start with job number 10 and run through to job number 100. When the upper limit has been reached you receive a message:
All job numbers in the range 00010:00100 are in use
At this point you need to remove some jobs from the spool - you can use the spool housekeeping functions to do this.
MF_NEWSPACE
Indicates whether SPACE is required for NEW datasets.
MF_PCRENAME_LAX
When an MVS dataset is renamed, the associated physical file is normally renamed only if it is in the Default Allocation Dataset Location. Set MF_PCRENAME_LAX to Y to enable physical files in other locations to be renamed if the cataloged name is changed.
MF_NODD
Specifies what action MSS is to take at run time if a job step uses a file that has not been allocated.
MF_RCCF
Enables Remote Job Step Execution (RJSE).
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_ARCHIVE_LOC
The location of the file where the contents of the MVS SPOOL spool file are copied prior to deletion.
MF_SPOOL_HK_TESTDATE
Spool housekeeping testing date override.
MF_SYSLOGDSN
The Syslog Dataset name.
MF_UCC11
Enables emulation of UCC11, a third party add-on to the mainframe that affects data set disposition processing. If UCC11 is enabled, a data set disposition of NEW is accepted even if the data set already exists.
Values
  • y
  • n (Default)
MF_USESCA5
Specifies that the server should use version 5 of the Open Service Component Architecture
Values:
  • ON (Default)
  • OFF
MF_USESCA7
Specifies that MSS accepts CA7 Scheduler control statements as comments rather than diagnosing them as errors.
Values:
  • ON (Default)
  • OFF
MFALLOC_LOC
The location of the default allocated dataset.
MFALLOC_PCFILE
When set to Y, which is the default, it will cause a catalogued file to be physically created if DSORG=PS is specified in the relevant DCB parameters.
MFALLOC_PROP
Rules for generated PC dataset names on allocation (that is, the default catalog PC DSN format).
MFAUDIT_LOGS
The location of audit files.
MFCODESET
Specifies which translation tables to use.
Values
  • A pre-defined country code:
    Country code | Language
    AUTOMATIC | Operating system default
    AUTO | Operating system default
    DEFAULT | US English
    0031 | Dutch
    0033 | French
    0034 | Spanish
    0039 | Italian
    0043 | German (Austrian)
    0044 | UK English
    0045 | Danish
    0046 | Swedish
    0047 | Norwegian
    0049 | German
    0066 | Thai Extended
    0081 | *Japanese Katakana Extended
    0082 | *Korean
    0086 | *Simplified Chinese
    0351 | Portuguese
    0358 | Finnish
    0437 | US English
    0500 | International (Latin 1)
    0886 | *Traditional Chinese
    0939 | *Japanese Latin Extended
    9122 | *Japanese Katakana

    Character sets marked with an asterisk (*) are capable of mixed single-byte and double-byte character conversion.

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

  • If you are not using UK or US language settings, you will also have to set the codepage in your PC environment settings:
    • Right click My Computer.
    • Select Properties.
    • Click Advanced system settings.
    • Click Environment Variables.
    • Under System Variables click New.
    • Enter MFCODESET as Variable name and XXXX as Variable value, where XXXX is your chosen codepage.
  • To use the Euro symbol (€), 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.
MFIMS_ACBDUMP_TIMESTAMP
Suppresses date/time stamp display in ACB report.
MFIMS_BMPCHKP
Returns a QC to a checkpoint call when it the call includes an IO area.
MFIMS_DIBSTAT_CODES
Specifies additional DIBSTAT return codes to be returned to EXEC DLI program.
MFIMS_DLI_OPT
Specifies DL/I call optimization flags.
MFIMS_DIAG
Enables IMS BTS format diagnostic tracing.
MFIMS_FLUSHTRACE
Flushes BTS trace file to disk after every write.
MFIMS_FP_DA
Bypasses keycheck on IMS Fastpath DB delete.
MFIMS_LOADMVS
Disables load of MVS support for IMS application programs.
MFIMS_PCBCALL
Allows a standalone EXEC DLI program to issue a PCB call.
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.
MFPLI_PRODUCT_DIR
The location of the Open PL/I installation. Used to find files needed for compiling and linking.
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
MFSYSCAT
The location of the JES system catalog.
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
MQSERVER
The location of a WebSphere MQ Server installation.
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.
PROCLIB
Specifies PROCLIB datasets. This can be a concatenation of PDS names.

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

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.
STEPLIB
The paths for Loader input load-members .390 files (must contain SYSLMOD) .
Note: For this environment, you can specify multiple paths, each separated by a semicolon.

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.
TX_MQTRACE
Enables tracing in dfh0mqis for WebSphere MQ calls.
TX_TN3270_FORCE_ALT
Enables you to use a screen size other than the default when using a TN3270 terminal emulator.
TXFILEP
The location of Micro Focus VSAM files.
TXMAPP
The location of the BMS load module.
TXRDTP
The location of MSS resource definition (RDO) files.
TXTRANP
The location of the CICS application object files.

U

USER
Default user name.

V

VSE_STARTUP_CFG
The location of the VSE JCL configuration file
Parent topic: Configuring Environment Variables
Related reference
CICS-Specific Environment Variables


Configuring Fileshare

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 (XARs)

In the X/Open XA model, Enterprise Server coordinates all XA activity, serving as an XA Transaction Manager (TM).

Enterprise Server works with XA-compliant Resource Managers (RMs) and manages the execution of:

  • Container-managed services such as Web services and EJBs
  • CICS or IMS transactions
  • JES jobs

RM access is provided for:

  • WebSphere MQ
  • SQL Server
  • ODBC (generic one-phase commit)
  • DB2 LUW
  • Oracle

XA-compliant Resources (XARs)

For Enterprise Server to work properly with an RM, an XAR must be defined. An XAR definition must include:

  • An xa_open string
  • An RM switch module
  • An XAR ID
xa_open string
A string that includes standard RM fields and values, and optionally, additional Micro Focus-specific fields and values.
RM switch module

A Micro Focus RM switch module is COBOL code that obtains the address of the XA switch data structure (xa_switch_t) provided by the RM, typically a database vendor. In addition, Micro Focus RM switch modules contain code that facilitates ease of use in Enterprise Server environments. RM switch modules are differentiated by their type, which is determined by the database vendor or other RM type. For example, you use an Oracle RM switch module type with Oracle databases, a WebSphere MQ switch module type for MQ resources, and so on.

Important: Source code for Micro Focus RM switch modules is available in Enterprise Developer, but is not included in the Enterprise Server stand-alone product. To use a Micro Focus RM switch module, you must build it in Enterprise Developer, deploy it to Enterprise Server, and then include it in an XAR definition.
XAR ID
The XAR ID uniquely identifies your XAR, and is used to identify the XAR to use in batch jobs, namely:
  • The SYSTEM parameter for IDAEFT01
  • The CONNECT function's subsystem parameter for DSNALI
  • The IDENTIFY function's subsystem parameter for DSNRLI

XARs in Enterprise Server

In Enterprise Server, you can define XARs, and edit and delete XAR definitions. You can also control which XARs are loaded when a specific enterprise server region starts.

  • Planning and Designing XARs
    Describes the considerations that apply to the planning and designing of XARs.
  • User Impersonation for CICS and JCL
    Describes using user impersonation to provide credentials other than those specified in the xa_open string.
  • WebSphere MQ Switch Module
    Describes the provided WebSphere MQ switch module.
  • Defining XARs
  • XA Troubleshooting
  • Handling XA Connection Errors
  • Recovery of in-doubt XA transactions
Parent topic: Configuring the Server Instance Environment


Planning and Designing XARs

Note: This topic does not apply to WebSphere MQ.

For a great majority of the applications that use XARs, the process of implementing an XAR is simple and straightforward, requiring only that you define the XAR inEnterprise Server. For more information about defining an XAR, see To define an XAR for an enterprise server region.

However, for a more complicated application, you need to plan ahead and design the required XAR(s) to accommodate the complexity of such an application. This can require modification and recompilation of application source code, and compilation of XAR switch module source code, which is provided with our Enterprise Developer product. For more information on this process, see the Planning and Designing XARs topic in your Enterprise Developer documentation.

After building a Micro Focus RM switch module in Enterprise Developer, you can include it in an XAR definition in Enterprise Server. An XAR definition includes an xa_open string, which is where you include specific RM syntax for the underlying RM.

In addition to the RM-specific xa_open string syntax, we provide several options that enable you to fine-tune your XAR definitions to yield maximum efficiency when running applications on Enterprise Server.

XARs support the following RM switch module types:

  • SQL Server
  • IBM DB2
  • Oracle
  • Generic one-phase commit for ODBC

Before configuring an XAR for an enterprise server region, we suggest that you consider the following:

Does the application require more than one XAR?
This depends on what database(es) the application accesses, and how the application interacts with it.
Do any applications require more than one XAR of the same RM switch module type?
If your application does not require more than one XAR of the same RM switch module type, then you are ready to define your XAR(s) in your enterprise server region .

However, in some scenarios, more than one XAR of the same type might be required for a CICS or Web services application. This likely requires recompilation of application source code. See Working with Multiple XARs in your Enterprise Developer documentation for more information.

Is the application coded to use distinct XARs?
Typically, the SQL code of CICS transaction or Web Services requests are stored in distinct source code modules – some modules used with only one database, and others used with another. Code constructed in this fashion can be compiled for each program module using the XAID compiler directive option set to the value of the appropriate XAR ID. This eliminates the need to change code.
Is it best to use a static or dynamic RM switch module in an XAR?
This depends on how the XAR is accessed by the application(s). See RM Switch Module Registration for more information.
Should transactions be run locally or globally?
This depends on the types of transactions executed. See the LocalTX=(T|F) section in SQL xa_open string Configuration Options for more information.
When and how should user credentials be obtained and applied?
You can configure an XAR to use xa_open-supplied user credentials, or to determine user credentials based on the current user. For more information, see User Impersonation for CICS and JCL and the UserP=(T|F) section in SQL xa_open string Configuration Options.
Are any of the required XARs used in batch jobs only?
If so, consider identifying these XARs as batch-only resources, which can save considerable overhead, and eliminate the need recompile using the XAID compiler directive option. For more information, see the BatchOnly=(T|F) section in SQL xa_open string Configuration Options.

For more information about configuring an XAR, see To configure an XAR for an enterprise server region.

Important: If you are using a dynamically registered RM switch module for either IBM DB2 or Oracle, and you plan to use User Impersonation, you must recompile your application source code with the XAID compiler directive option before deploying the application to Enterprise Server. See XAID for more information.
Note: The WebSphere MQ module provided is a built module, not a source code file. It is available in both your development and deployment environments. See the WebSphere MQ topic for more information.
  • RM Switch Module Registration
    Describes the two types of transaction registration available for RM switch modules.
  • Working with Multiple XARs
    Presents several use case scenarios that address requirements for using multiple XARs.
  • SQL xa_open string Configuration Options
    Describes Micro Focus-specific xa_open string options available for defining XARs.
Parent topic: Using XA-compliant Resources (XARs)
Related concepts
Working with Multiple XARs
RM Switch Module Registration
SQL xa_open string Configuration Options
WebSphere MQ Switch Module
Related tasks
To define an XA resource (XAR) for an enterprise server region


RM Switch Module Registration

In an XAR definition, you can specify that an RM switch module be registered either statically or dynamically:

Static registration
The switch module is registered for all transactions even if it does not participate in the transaction.
Dynamic registration
The switch module is registered for a transaction dynamically by the RM itself, with the first SQL call to the RM.

In general, dynamic registration is preferred because it requires less overhead, especially when multiple XARs have been defined.

As discussed in Building RM Switch Modules, both static and dynamic versions of an RM switch module are created during generation.

Once you have generated your switch modules, you specify either the dynamic or the static module as part of the XAR definition - the field module. This tells the enterprise server region what module to use and whether to register it statically or dynamically. See Defining XARs for more information.

Parent topic: Planning and Designing XARs
Related concepts
Planning and Designing XARs
Defining XARs


Working with Multiple XARs

Enterprise Server supports multiple XARs defined for a single enterprise server region. The following scenario provide XAR configuration recommendations that yield the best results when using multiple XARs:

Note: Some additional scenarios require modifications to and recompilation of application source code. To review these scenarios, see the Working with Multiple XARs topic in your Enterprise Developer documentation.
Scenario: Multiple XARs of different RM switch module types
For a single enterprise server region, you can define and use one XAR for each RM switch module type. A simple scenario such as this does not require any recompilation of source code, nor does it require special XAR configuration. Enterprise Server handles all CICS transactions, Web services, and batch jobs correctly.
Scenario: Multiple XARs of the same type

In this scenario, suppose your application requires three XARs, all of the same type, but only one XAR is required for CICS applications. The other two are used in batch jobs only.

Here, you define the XAR for the CICS application with no special configuration options, and the two XARs used for batch jobs by including BatchOnly=T in the xa_open string. See SQL xa_open string Configuration Options for more information.

Parent topic: Planning and Designing XARs
Related concepts
Planning and Designing XARs
SQL xa_open string Configuration Options


SQL xa_open string Configuration Options

Describes Micro Focus-specific xa_open string options available for defining XARs.

Enterprise Server provides xa_open string options for XARs in addition to those provided by each database vendor.

You can add these options to a resource definition by including them in the xa_open string using the format specified by the database vendor. For example, most databases use a comma separator (,), but Oracle uses a plus sign (+) separator. See your database documentation for more information.

UserP={T|F}
Determines how to establish the identity of the current Enterprise Server user for each CICS transaction or batch job.
T
The identity for the connection is established via the credentials of the current Enterprise Server user for each CICS transaction or batch job. This is known as User Impersonation. To use this option, the credentials supplied in the open string must be for an account that can impersonate other users, but otherwise should have minimal database privileges and access rights. See User Impersonation for CICS and JCL for more information.
Note:
  • DB2 and Oracle - When UserP=T is set for a DB2 or an Oracle XAR that uses dynamic registration, you must build the module in Enterprise Developer and specify the XAID compiler directive option.
  • One-phase commit for ODBC - UserP=T is supported only for SQL Server .
  • User Impersonation is not supported for Web services.
F
The identity for the connection is established via the credentials supplied in the xa_open string and does not change. Default.
BatchOnly={T|F}
Determines the availability of XA resources in Enterprise Server SEPs.
T
Makes the associated XAR available in Enterprise Server via JCL only for batch jobs and their corresponding SEPs only. This saves transactional workload overhead because it does not require that a connection be opened in other Enterprise Server SEPs.
F
Makes the associated XAR available in all Enterprise Server SEPs. Default.
LocalTX={T|F}
Determines how the XAR handles transactions.
T
The associated XAR uses local (non-distributed) transactions. This option reduces overhead, and therefore can be a good option when using a single XAR. Be advised, however, that LocalTX=T also handles commits and roll backs for each XAR, independent of other resources, and should be used with care. Avoid setting LocalTX=T on jobs that use both VSAM and SQL.
F
The associated XAR uses XA distributed, global transactions. Default.
Parent topic: Planning and Designing XARs
Related concepts
Planning and Designing XARs
Working with Multiple XARs
SQL Server RM Switch Module
SQL Server xa_open string
Generic one-phase commit for ODBC xa_open string
IBM DB2 xa_open string
Oracle xa_open string


User Impersonation for CICS and JCL

The SQL RM switch modules allow CICS- and JES-initiated transactions to execute using different user credentials than those specified within the xa_open string. This is called user impersonation. The credentials used instead are for:

  • CICS - the user currently logged in
  • JCL - the user specified in the job card

With user impersonation, the credentials specified in the open string for each XAR must be for an account that can impersonate other users, but otherwise has minimal database privileges and access rights.

Note: For JCL, if no user ID is specified on the job card, the batch job will run with database user ID JESUSER. If the CICS transaction is run without a CICS login, it will execute with database user ID CICSUSER.
CICS processing
For CICS processing, create a CICS user ID with the same name as the database user ID you want to impersonate. If you are using internal Enterprise Server security, you can use the Enterprise Server Monitor and Control (ESMAC) feature to create and administer CICS user IDs. If, however, you are using an external security manager, configure the user ID via LDAP. For more information, see Environment Variables used in Enterprise Server Security. For general details on CICS user IDs for Enterprise Server security, see Enterprise Server Security.
JES and CICS processing
For both JES and CICS processing, be sure that the impersonated user IDs, which are the actual database user IDs used, have sufficient database privileges to execute the code and access the underlying database tables.
  • SQL Server User Impersonation Configuration
    Describes the setup required to use SQL Server user impersonation with an XAR.
  • Oracle User Impersonation Configuration
    Describes the setup required to use Oracle user impersonation with an XAR.
  • IBM DB2 User Impersonation Configuration
    Describes the setup required to use IBM DB2 user impersonation with an XAR.
Parent topic: Using XA-compliant Resources (XARs)
Related concepts
Enterprise Server Security
Related reference
Environment Variables used in Enterprise Server Security


SQL Server User Impersonation Configuration

To find the appropriate database user credentials for CICS transactions or batch jobs, the SQL Server XA switch module issues the Transact-SQL EXECUTE AS statement. For the EXECUTE AS statement to work properly, you must include a GRANT IMPERSONATE statement in your SQL Server login/user ID security environment. This enables the xa_open user ID to impersonate the appropriate database user ID.

The following is provided as a simple example. Your security and database environment might dictate a different implementation. Please review the Microsoft documentation on the EXECUTE AS statement and other related topics before implementing your solution:

  1. Create the user cited in the xa_open string:
    CREATE LOGIN [XAOPENUSER] WITH PASSWORD=N'XAOPEN',
              DEFAULT_DATABASE=[mfdb], DEFAULT_LANGUAGE=[us_english],
              CHECK_EXPIRATION=OFF, CHECK_POLICY=OFF
CREATE SCHEMA [XAOPENUSER]
CREATE USER [XAOPENUSER] FOR LOGIN [XAOPENUSER] WITH
              DEFAULT_SCHEMA=[XAOPENUSER]
  2. Create the user FRITZ, without login capability, to execute CICS or JCL:
    CREATE SCHEMA [FRITZ]
CREATE USER [FRITZ] WITHOUT LOGIN WITH DEFAULT_SCHEMA=[FRITZ]
  3. Create user ALLIE, with login capability, to execute CICS or JCL:
    CREATE SCHEMA [ALLIE]
CREATE USER [ALLIE] FOR LOGIN [ALLIE] WITH DEFAULT_SCHEMA=[ALLIE]
  4. Grant database privileges to FRITZ and ALLIE:
    Note: This is example code. Your own code might require modification to comply with your specific database security policies.
    ALTER ROLE [db_owner] ADD MEMBER [SCOTT]
ALTER ROLE [db_owner] ADD MEMBER [ALLIE]
GRANT SELECT ON SCHEMA1.TABLE1 TO SCOTT
GRANT ALL  ON SCHEMA1.TABLE1 TO ALLIE
  5. Grant impersonate privileges to the xa_open string user to enable the xa_open string user to become ALLIE or FRITZ:
    Note: Once again, this is example code.
    GRANT IMPERSONATE ON USER:: FRITZ TO XAOPENUSER;
    GRANT IMPERSONATE ON USER:: ALLIE TO XAOPENUSER;
Parent topic: User Impersonation for CICS and JCL


Oracle User Impersonation Configuration

To find the appropriate database user credentials for CICS transactions or batch jobs, the Oracle XA switch module uses proxy authentication, calling the OCI function OCIAttrSet() with the parameter OCI_ATTR_PROXY_CLIENT. For this call to work properly, you must include an ALTER USER GRANT CONNECT THROUGH statement in your Oracle user credentials environment. This enables the xa_open user ID to impersonate the appropriate database user ID.

The following is provided as a simple example. Your security and database environment might dictate a different implementation. Please review the Oracle documentation on proxy authentication and other related topics before implementing your solution:

  1. Create the user cited in the xa_open string:
    CREATE USER XAOPENUSER IDENTIFIED BY XAOPENUSER
GRANT "CONNECT" TO MFESPROXY
  2. Create the user FRITZ to execute CICS or JCL:
    CREATE USER FRITZ IDENTIFIED BY FRITZ
GRANT "CONNECT” TO FRITZ
  3. Grant database privileges to FRITZ:
    GRANT ALL ON SCHEMA1.TABLE1 TO FRITZ
GRANT "RESOURCE" TO FRITZ
  4. Grant impersonate privileges to the xa_open string user to enable the xa_open string user to become FRITZ:
    ALTER USER FRITZ GRANT CONNECT THROUGH XAOPENUSER
Parent topic: User Impersonation for CICS and JCL


IBM DB2 User Impersonation Configuration

To find the appropriate database user credentials for CICS transactions or batch jobs, the IBM DB2 XA switch module uses trusted connections, calling the CLI function SQLSetConnectAttr () with the parameter SQL_ATTR_TRUSTED_CONTEXT_USERID. For this call to work properly, you must also create a TRUSTED CONTEXT. This enables the xa_open user ID to impersonate the appropriate database user ID.

The following is provided as a simple example. Your security and database environment might dictate a different implementation. Please review the IBM documentation on trusted connections and other related topics before implementing your solution.

  1. Create the user cited in the xa_open string
  2. Create the user FRITZ to execute CICS or JCL
  3. Grant database privileges to FRITZ
  4. Because the trusted context works exclusively with TCPIP client-server communication, set up a TCPIP client-server communication environment by cataloging a TCPIP node to use with the database, if one doesn't already exist:
    db2 catalog tcpip node tcpnode remote OOH-CHRISLE-701 server 50000
  5. Catalog database access using an alias:
    db2 catalog db sample as tcpsamp at node tcpnode
  6. Specify the alias created (tcpsamp) as the DB parameter in your xa_open string.
  7. Grant impersonate privileges to the xa_open string user so it can impersonate FRITZ:
    CREATE TRUSTED CONTEXT ctx1 BASED UPON CONNECTION USING SYSTEM AUTHID  XAOPENUSER  ATTRIBUTES (ADDRESS 'OOH-CHRISLE-701' ) ENABLE
ALTER TRUSTED CONTEXT ctx1 ADD USE FOR FRITZ WITHOUT AUTHENTICATION
Parent topic: User Impersonation for CICS and JCL


WebSphere MQ Switch Module

Describes the provided WebSphere MQ switch module.

Fully functional 32- and 64-bit WebSphere MQ switch modules are provided as part of Enterprise Server. The filenames and locations of these built modules are:

Filename | Default Location
esmqxa.dll | %ProgramFiles(x86)%\Micro Focus\Enterprise Server\bin
esmqxa.dll | %ProgramFiles(x86)%\Micro Focus\Enterprise Server\bin64

By default, these switch modules operate in two-phase commit mode. If instructed by Micro Focus SupportLine to change the operation to one-phase commit mode, you can do this by setting the ES_MQ_1PC environment variable to Yes or True.

Note: Depending on how you configure Enterprise Server, you might not need an XA switch for WebSphere MQ. See Configuring Enterprise Server for IBM WebSphere MQ for more information.
Parent topic: Using XA-compliant Resources (XARs)
Related concepts
Planning and Designing XARs
Configuring Enterprise Server for IBM WebSphere MQ


Defining XARs

  • To define an XA resource (XAR) for an enterprise server region
  • To Delete an XA Resource
  • To Edit an XA Resource
  • To Enable or Disable an XA Resource
Parent topic: Using XA-compliant Resources (XARs)
Related concepts
RM Switch Module Registration


To define an XA resource (XAR) for an enterprise server region

  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left in the row for the enterprise server region that you want to edit.
  2. Click the XA Resources tab.
  3. Click Add.
  4. Specify the details of the XAR:
    ID
    Specify an XA resource manager (XAR) ID, used internally to identify a particular XA configuration, and must be unique within the enterprise server region. This ID is used by JES-initiated jobs. See Executing TSO Commands in Batch Mode (IDAEFT01), and Planning and Designing XARs for more information. Mandatory.
    Name
    Specify the name by which the XAR 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 RM switch module executable file (.dll) that contains the entry point that returns the xa_switch_t structure to the enterprise server. We strongly recommend that you include the full path to the executable file. 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 often the user ID and password credentials for connecting to the database. The contents of this string are database-specific.

    Where the RM switch module 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 XAR 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 XAR definition.
    Enabled
    Check this to enable the XAR. It is checked by default.
    Important: For more information on the syntax for Open string, see the xa_open string topic for your database type, listed below.
  5. Click Add.
Note: You cannot add an XAR until all the mandatory fields have values.
  • SQL Server xa_open string
  • Generic one-phase commit for ODBC xa_open string
  • IBM DB2 xa_open string
  • Oracle xa_open string
  • XAR for WebSphere MQ
Parent topic: Defining XARs
Parent topic: Work with Servers
Parent topic: Database Managers Supported
Related concepts
Planning and Designing XARs


SQL Server xa_open string

To complete the definition of a SQL Server XAR, add the following values in the Open string field:

DSN=odbc_dsn[,USRPASS=userid.password][,CONNECTNAME=connectname]
   [,TM=tmname][,RMRECOVERYGUID=guid][,TIMEOUT=timeoutvalue]
   [,USERP={T|F}][,BATCHONLY={T|F}][,LOCALTX={T|F}]
odbc_dsn
The ODBC Data Source Name used to connect to the data source as defined within the Windows ODBC Data Source Administrator utility.1
userid
The user ID required to connect to the data source. Not required when using trusted connections.1
password
The password required to connect the user ID to the data source. Not required when using trusted connections. 1
connectname
The name used by OpenESQL to identify the connection. Specify this only if you have multiple connections.2
tmname
The transaction manager name used for diagnostics by the Microsoft Distributed Transaction Coordinator (MSDTC). We recommended that you specify the transaction manager name as a string that uniquely identifies the host machine and Enterprise Server region. The tmname value is restricted to 40 characters. If not specified, the TM value defaults to Micro Focus Enterprise Server.
guid
A 36-character GUID used to optimize recovery processing.
timeoutvalue
The amount of time in milliseconds that MSDTC waits for transactions to complete. If not specified, the default is 0, meaning no time limit.
USERP, BATCHONLY, LOCALTX
See SQL xa_open string Configuration Options for details.
1 Alternatively, you can specify the DSN, user ID, and password by manually coding them into the esmssql.cbl source. This can be helpful if you want to ease security. To do this, search for CUSTOMIZE within esmssql.cbl to see where to apply the required changes.
2 You must also code a reference to this connection name into the source for your deployed container-managed service as follows:
EXEC SQL SET CONNECTION connectname END-EXEC
Where connectname is the name specified in the Open string field on the Enterprise Server XA Resources tab.
Note:
  • If you specify any parameter other than those listed here, the switch module returns an error to Enterprise Server.
  • The SQL Server switch module does not accept the DTCSERVER parameter. Consequently, it is not possible to define the resource manager to identify a specific machine to act as the transaction coordinator in the XAR. However, using Windows Component Services, you can configure a remote machine to act as the transaction coordinator. To do this, on your local machine, change the default MSDTC properties to use a remote coordinator, specifying the computer name of the remote machine as the remote coordinator host name. See your Windows documentation for complete instructions.

Configuring MSDTC and SQL Server to act as an XA resource manager

  1. Start the Windows Component Services Administrative tool.
  2. Open the Properties page for Component Services > Computers > My Computer > Distributed Transaction Coordinator > Local DTC.
  3. On the Security tab, check Enable XA Transactions.

Configuring a remote machine to act as transaction coordinator

Using a remote machine as a transaction coordinator could improve performance because Enterprise Server and SQL Server are not required to compete for resources on the same machine. To configure a remote machine to act as a transaction coordinator:

  1. On the host machine, start the Windows Component Services Administrative tool.
  2. Open the Properties page for Component Services > Computers > My Computer.
  3. On the MSDTC tab, uncheck Use local coordinator.
  4. In the Remote coordinator host name field, type the computer name or IP address of the machine you want to act as the transaction coordinator, or click Select to select a machine.
Parent topic: To define an XA resource (XAR) for an enterprise server region
Related concepts
SQL xa_open string Configuration Options


Generic one-phase commit for ODBC xa_open string

To complete the definition of a generic one-phase commit for ODBC XAR, add the following values in the Open string field.

DSN=odbc_dsn[,USRPASS=userid.password]
   [,USERP={T|F}][,BATCHONLY={T|F}][,LOCALTX={T|F}]
odbc_dsn
The ODBC Data Source Name used to connect to the data source as defined within the Windows ODBC Data Source Administrator utility.
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.
USERP, BATCHONLY, LOCALTX
See SQL xa_open string Configuration Options for details.

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 define an XA resource (XAR) for an enterprise server region
Related concepts
SQL xa_open string Configuration Options


IBM DB2 xa_open string

To complete the definition of an IBM DB2 XAR, add the following values to the Open string field. Enclose values containing spaces in double quotes.

DB=name,UID=identifier,PWD=password,AXLIB=casaxlib
[,SREG={T|F}][,TCTX={TRUE|FALSE}]
   [,USERP={T|F}][,BATCHONLY={T|F}][,LOCALTX={T|F}]
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.
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.
SREG
Static Registration flag (optional). To register the XA switch module statically, you must set SREG=T. Set SREG=F or do not specify SREG to omit static registration (Default).
TCTX
Specifies whether or not the transaction should use a trusted connection. Set this to TRUE instruct transaction manager to attempt to open a trusted connection. Set this to FALSE to omit the instruction (Default).
Important: If you are configuring your XAR for user impersonation (setting UserP=T), you must also add TCTX=TRUE to the Open string field.
USERP, BATCHONLY, LOCALTX
See SQL xa_open string Configuration Options for details.
Parent topic: To define an XA resource (XAR) for an enterprise server region
Related concepts
SQL xa_open string Configuration Options


Oracle xa_open string

To complete the definition of an Oracle XAR, add the following values to the Open string field. Enclose values containing spaces in double quotes:

LogDir=path+DbgFl=value+Oracle_XA+SesTm=time+SqlNet=name+Acc=P/user/password
   [,USERP={T|F}][,BATCHONLY={T|F}][,LOCALTX={T|F}]
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.
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/".
USERP, BATCHONLY, LOCALTX
See SQL xa_open string Configuration Option for details.
Parent topic: To define an XA resource (XAR) for an enterprise server region
Related concepts
SQL xa_open string Configuration Options


XAR for WebSphere MQ

To define the WebSphere MQ XAR in Enterprise Server, you use the MFDS browser interface, ensuring that the server is not started:
  1. Click Edit against the region you want to update.

    This action takes you to the General properties tab.

  2. Click on the XA Resources tab.
  3. Click Add to open the new definition page.

You can now add an XA resource including the following values:

  1. In the ID field, type the four-character identifier for this XA resource; for example, XAMQ.
  2. In the Name field, type the name of this XA resource.
  3. In the Module field, type esmqxa.dll.
  4. In the Open string field, type the following:
    TPM=CICS,AXLIB=casaxlib,QMNAME=queue_manager_name,CHANNEL,TRPTYPE,CONNAME
    where the parameters are:
    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.
    QMNAME
    The name of the queue manager. This is a mandatory parameter.
    CHANNEL
    Optional - the name of an MQI channel. If this parameter is supplied, the CONNAME parameter must also be supplied.
    TRPTYPE
    Optional - the communications protocol for the MQI channel. The default is TCP. The following are valid values:
    LU62
    SNA LU 6.2
    NETBIOS
    NetBIOS
    SPX
    IPX/SPX
    TCP
    TCP/IP
    CONNAME
    Optional - the network address of the queue manager (connection name). 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.

    Example Open String

    TPM=CICS,AXLIB=casaxlib,QMNAME=TESTQ,CHANNEL_TESTQ,TCP,123.10.20.135(1414)
    Note: If you specify the CHANNEL, TRPTYPE, and CONNAME parameters, you must also set the MQSERVER environment variable, providing the same parameter values. See WebSphere MQ-Specific Environment Variables for more information.
  5. The Close string field is not required.
  6. You can type a note in the Description field to aid identification of this XA switch module.
  7. Check the Enabled box to ensure that the XA switch module is available.
  8. Click Add to create the resource.
Parent topic: To define an XA resource (XAR) for an enterprise server region
Related reference
WebSphere MQ-Specific Environment Variables


To Delete an XA Resource

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: Defining XARs
Parent topic: Work with Servers


To Edit an XA Resource

  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: Defining XARs
Parent topic: Work with Servers


To Enable or Disable an XA Resource

  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: Defining XARs
Parent topic: Work with Servers


XA Troubleshooting

  • XA Troubleshooting
  • XA Return Codes
  • XA Switch Module Diagnostics
Parent topic: Using XA-compliant Resources (XARs)


XA Troubleshooting

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-tran-no | 6 numeric | CICS task number
xid-mgr-id | 18 numeric | Position of this resource manager in the resource manager table
xid-branch-no | 6 numeric | Branch number
For example, the XID
MF_CASDEMOCICS-FS 000049000000000000000001000001
is made up of the following:
  • MF_CAS is a constant
  • DEMO is the system ID
  • CICS-FS is the region
  • 000049 is the task number
  • 000000000000000001 indicates this is the first resource manager in the table
  • 000001 indicates this is the first branch

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

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

SQL Server, DB2, Oracle and ODBC
The SQL Server, DB2, Oracle, 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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\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.

SQL Server
Microsoft provides a downloadable tool, DTCPing, to help diagnose MSDTC configuration problems. We suggest that you use this tool and review relevant Microsoft MSDTC documentation as required to troubleshoot the SQL Server switch module.
Parent topic: XA Troubleshooting
Related information
Components Traced by CTF


Handling XA Connection Errors

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, and an error occurs on a call to XA, the server attempts to reconnect to the resource manager.

Each time an XA transaction is executed, and an XA call fails, the retries counter is incremented. You can control the number of times an XA call can fail with the next environment variable.

Restriction: ES_XA_RECONNECT is not supported for resource managers using dynamic registration.
ES_XA_????_NB_RETRIES
This environment variable controls the number of times that the server attempts to retry a failed XA call. The format for setting this environment variable is:
ES_XA_????_NB_RETRIES=nnnn

where ???? defines the XA ID, and nnnn is the number of attempts to retry the XA call before the SEP is recycled, and the switch disabled. The default value 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:

When the region is started, an XA switch module is loaded for each SEP, and an xa_open call is made. If the xa_open fails the switch is immediately disabled.

If the initial xa_open call is successful:
  • Each time an XA transaction is executed, and an XA call fails, the retries counter is incremented.
  • 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 Enterprise Server Monitoring and Control (ESMAC) to reenable the switch after the problem with the database is fixed.

If the maximum number of call failures is reached, thereby disabling your switch module, and ES_XA_RECONNECT is set to True, you can reenable the switch by starting 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 Enable.
Parent topic: Using XA-compliant Resources (XARs)


Recovery of in-doubt XA transactions

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 (XARs)


Configuring and Administering Enterprise Server Instances

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

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

  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. Choose a server type:
    • Click Micro Focus Enterprise Server if you plan to run COBOL application programs as services in a service-oriented architecture.
    • Click Micro Focus Enterprise Server with Mainframe Transaction Option if you plan to run CICS or JCL applications that have been migrated from the mainframe.
  5. Click Next>>.
  6. 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.
  7. 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 %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\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.

  8. Specify the start-up configuration you want in the fields under Startup Options.
  9. Specify any trace flags you want to be set in the fields under Trace Flags.
  10. 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.
  11. Specify a text description of the server in Description (optional).
  12. Click Add.
Parent topic: Creating and Configuring Enterprise Server Instances
Parent topic: Work with Servers


To Change the Number of ES licenses

  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

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

  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

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

  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 C:\Users\All Users\Micro Focus\Enterprise Developer\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
Parent topic: Work with Servers


Connecting to a Server Instance

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

  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
Parent topic: To change the SIT associated with a server
Related concepts
Configuring IMS Printers
Related tasks
To define specific printers for an IMS-enabled enterprise server
To attach to an IMS printer
To enable printer security for an IMS-enabled enterprise server
Related information
Configuring and Starting Transaction Data Collection
Viewing HSF Information in ESMAC


To stop a server Instance

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
Parent topic: To change the SIT associated with a server


To Edit an Enterprise Server Instance

  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, MSS, 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

  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

  • 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

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).
ES_WORKING_MODE | The working mode of the server. This indicates whether the server is to run 32-bit or 64-bit applications.
MFDS_PORT | The port on which the Directory Server listens (usually 86).
For example, the start script could be used to set environment variables for the server, as follows;
set MY_VARIABLE=value
rem 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 would need third-party tools to do this on Windows.

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 Windows batch file, 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

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

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
Parent topic: Resources
Parent topic: To change the SIT associated with a server
Related concepts
Configuring IMS Printers
Defining IMS Resources
IMS-enabled Enterprise Server Administration using ESMAC
Related tasks
To define specific printers for an IMS-enabled enterprise server
To attach to an IMS printer
To enable printer security for an IMS-enabled enterprise server


To Shut Down a Server from ESMAC

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
Parent topic: Administer a Server Using ESMAC


Viewing Enterprise Server Instance Details

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

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

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

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

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

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, Micro Focus recommends 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, Micro Focus recommends that you do configure an mfuser, and give mfuser only minimum privileges, which must include the ability to start a region. See also ES_USR_DFLT_ESMAC.

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

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

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
  • Create and view traces for SEPs
  • Trace and stop JES initiators
Parent topic: Managing an Enterprise Server Instance's SEPs


To Change the Number of SEPs

  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

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

  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
Parent topic: Administer a Server Using ESMAC


Stopping and Restarting an Installation

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

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 Enterprise Developer installation, from the Start menu, select: Start > All Programs > Micro Focus Enterprise Developer> 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.
  • casstart
    Starts an enterprise server.
  • casstop
    Stops an enterprise server.
Parent topic: Configuring and Administering Enterprise Server Instances


casdump

Forces a system dump.

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
/i | Trigger an IMS TM dump
/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.
Note: The parameters /d and /i cannot be used at the same time.

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.

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


casstart

Starts an enterprise server.

Syntax:

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

Parameters:

/res-name | Name of the enterprise server to start. Defaults to ESDEMO
/oconfig-name | When using this option in MSS enabled regions, the config-name should be the name of a SIT. The region will start up using the specified SIT rather than the one defined in the Enterprise Server Administration pages.
/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.

You can only invoke the casstart command from the command line or from the Micro Focus Directory Server (MFDS); it cannot be invoked, for example, from a batch job.

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


casstop

Stops an enterprise server.

Syntax:

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

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.
  • 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.
Note: When calling this utility from JCL or 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 required only 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.

/ttransaction-id | The MSS shutdown transaction to run. If none is specified, this defaults to CQIT.
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.

Return Code:

If a serious error occurs, a value of 15 will be set in the return code; other, lower values may also be returned. A message explaining the error is displayed on stdout and the console log. If you are calling casstop from within your own application program, then the message is displayed only on the console log.

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


Enterprise Server Clustering

An Enterprise Server Cluster is a cluster of interconnected Enterprise Server regions, orchestrated by a specific instance of an Enterprise Server region called the Global Lock Manager (GLM).

An Enterprise Server Cluster allows the scaling-out of work units, so that an increased number of operating system images can share the workload. Built over the ISC communications layer, an Enterprise Server Cluster allows catalog dataset sharing and ensures the integrity and consistency of data throughout the entire cluster.

The end result is high-performance, multi-system data sharing across all systems.
Note: In the current version of Enterprise Server Clustering, only JES work requests can benefit from the global lock processing in a cluster.
  • Topology
    An Enterprise Server Cluster employs a logical star topology - each cluster instance is connected to a central cluster instance called the Global Lock Manager (GLM).
  • The Global Lock Manager
    An Enterprise Server Cluster is interconnected to, and orchestrated by, a specific instance of an Enterprise Server region called the Global Lock Manager (GLM).
  • Configuration
    Setting up an Enterprise Server Cluster requires minimal configuration.
  • Recovery
    Depending on the failure scenario, a recovery situation can involve the planned execution of several remedial activities.
  • Failure Modes
    During a catastrophic GLM failure, all Enterprise Server Cluster members are dependent upon the Global Lock Manager (GLM) for the successful completion of all active jobs. In a permanent connection loss situation, system administrator actions may need to be taken on the GLM and the client.
  • Lock Processing
    There are several ways to browse and edit Enterprise Server Cluster locks.
  • JCL Submission
  • RNL Support
    RNLs are an IBM mainframe method used by GRS to identify resource scope. Of the RNLs functions, only those essential for identification of a SYSZDSN lock scope have been implemented.
  • Environment variables
    An Enterprise Server Cluster requires minimal configuration. The only mandatory environment variables are ES_CLUSTER, which should be set in every region that is participating as a member of a cluster, and ES_GLM, which should be set in the region designated as the Global Lock Manager (GLM).
  • The CASGLM.LCK file
    The CASGLM.LCK file stores important information about the state of an Enterprise Server Cluster.
  • Tracing
    ESMAC provides access to several Enterprise Server Cluster tracing facilities.
Parent topic: Enterprise Server configuration and administration


Topology

An Enterprise Server Cluster employs a logical star topology - each cluster instance is connected to a central cluster instance called the Global Lock Manager (GLM).

An Enterprise Server Cluster is composed of a minimum of two Enterprise Server Cluster clients and a single Enterprise Server Cluster lock manager - the GLM. In practice, the number of Enterprise Server Cluster clients is determined by the volume of JES work required - jobs can be submitted to any members of a cluster.

If desired, an Enterprise Server Cluster can present a single interface for job submission. Jobs can be submitted to a specialized instance of a cluster member - a scheduler region, which can itself execute JES work as well as orchestrate it. It is also possible for the GLM to act as a scheduler region - but we strongly advise (although do not enforce) that no work other than global locks processing is executed by the GLM. For example, it is inadvisable to create initiators on the GLM machine.

Current limitations:

  • If you submit jobs to a region that has no initiator, the first Enterprise Server Cluster server that requests work from the Job Manager for the target class will execute the work. This implies latency at least equal to the difference in time between when the relevant casmgr process requested the job from the Job manager, and the time at which the JCL was submitted. This latency will be addressed in a future release.
  • It is only possible to define a single GLM.
Parent topic: Enterprise Server Clustering


The Global Lock Manager

An Enterprise Server Cluster is interconnected to, and orchestrated by, a specific instance of an Enterprise Server region called the Global Lock Manager (GLM).

The GLM is a specialized instance of an Enterprise Server region whose sole role is to process global lock requests. A GLM machine should typically have a large memory as all locks are memory-resident.

In an Enterprise Server Cluster, all cluster members - including the GLM - must share the CATALOG.DAT and the Dataset Allocation Default Location (DADL). This configuration defines the role of the GLM which is to protect against file corruption: the GLM acts as a lock manager for all global scope locks. In addition, all cluster members must be on the same domain. This restriction is imposed as the system uses SYS-C definitions to identify cluster participants, and SYS-C definitions use a 16 character identifier, whereas a host on a separate domain has an identifier of up to 255 characters.

In an Enterprise Server instance that is not a member of a cluster, the lock manager processes the locks across all of the batch initiators within this single region. In an Enterprise Server instance that is a member of a cluster, a copy of that same lock manager runs on the GLM and manages the locks across all batch initiators of all members of the cluster.

A key responsibility of the lock manager is to ensure that when a job is accessing files with exclusive locks, no other jobs can access these files until the blocking job has released its locks.

In the extract from a console.log below, it is the GLM that has placed JOB01694 in a wait state while it requests use of datasets SYSI.MAIN01.GENE001 and SYSI.MAIN01.SPEC001.

JCLCM0188I JOB01694 JRX0035 JOB STARTED 10:29:51
 MVSXR0091I JOB01694 JRX0035 Waiting for shared use of dataset "SYSI.MAIN01.GENE001". 10:29:51
 MVSXR0091I JOB01694 JRX0035 Waiting for shared use of dataset "SYSI.MAIN01.SPEC001". 10:29:51
 MVSXR0093I JOB01694 JRX0035 Required datasets have been acquired. Execution resumed. 10:29:55

At 10:29:55, the job resumes as the requested locks have been acquired.

The scope of a lock server (local) or servers (global) is defined using Resource Name Lists (RNLs).

Parent topic: Enterprise Server Clustering


Configuration

Setting up an Enterprise Server Cluster requires minimal configuration.

Common configuration for all Enterprise Server Cluster members

All members of an Enterprise Server Cluster, including the Global Lock Manager (GLM), must have the JES subsystem enabled and share the same system catalog and Data Allocation Default Location (DADL). These settings are typically defined on the JES tab of a region definition.

These settings are verified during the handshake between each Enterprise Server Cluster client and the Enterprise Server GLM. The location and name must match for all regions in the cluster. If a mismatch is found, the following message is sent to the console.log:

TXSI5014S Severe error in ES cluster negotiation with parm 1 (parm 2), region terminating

The message will further display whether the mismatch was discovered in the CATALOG.DAT location or the DADL.

Following a successful handshake, the message:

CASSI5012I Successfully negotiated with ES Cluster manager GLMAPPLID

is displayed in the console.log.

In addition, all members of an Enterprise Server Cluster, including the GLM, must have the following environment variable set:
ES_CLUSTER
Cluster members identify themselves by checking the existence of environment variable ES_CLUSTER in their environment space. Any value sets the variable - e.g. ES_CLUSTER=YES.

Configuring the Enterprise Server Cluster GLM

The GLM is configured using environment variables:
ES_GLM
The GLM identifies itself by checking the existence of environment variable ES_GLM in its environment space. Any value sets the variable - e.g. ES_GLM=YES.
ES_GLM_TIMEOUT=60
This environment variable can be set on the GLM only. From this value, defined in seconds, the system will derive the number of retries made to the GLM if a communication error is encountered before the status of the connections to the Enterprise Server Cluster is marked as Disabled. The value set on the GLM is pushed to all clients.

Configuring Enterprise Server Cluster members

There is no further configuration required for an Enterprise Server Cluster member.

An instance of Enterprise Server automatically becomes an Enterprise Server Cluster client if:
  • It shares its system catalog and DADL with all members of the cluster.
  • It sets a value for the environment variable ES_CLUSTER.
  • The GLM is started prior to this server instance, or a file called CASGLM.LCK already exists and contains a list of the Enterprise Server Cluster members and their state - active or inactive.

Configuring dataset scope

The scope of a dataset is determined by Resource Name Lists (RNLs). All RNLs must be created in a single file whose name and location is not configurable.
  • Name: ESCLRNLs.cfg
  • Location: Create the ESCLRNLs.cfg file in the same folder as that used by the system catalog.
If the GLM does not find an ESCLRNLs.cfg file, it creates one by default and writes a single line:
RNLDEF RNL(INCL)TYPE(GENERIC) QNAME(SYSZDSN)
This will result in a global scope set for all SYSZDSN.

ISC listeners and SYSC connections

Cluster members communicate over the Micro Focus ISC interface. Dynamically-created ISC listeners and ISC connections are activated between each Enterprise Server Cluster client and the Enterprise Server Cluster manager. There are no requirements to define ISC listeners and/or SYSC connections. The information required to create the ISC resources is collected dynamically and stored in the CASLGM.LCK file by the GLM, and later consumed by all members of the Enterprise Server Cluster.

ISC-based connections will be identified by APPLID and SYSID, therefore APPLIDs and SYSIDs must be unique throughout the system.

The APPLID is derived from the Enterprise Server name, so it's simple to ensure that all Enterprise Cluster members have different names.

The SYSID is defined in the System Initialization Table (SIT). Each Enterprise Server Cluster member will require its own SIT. The same resource definition file can be used across the whole Enterprise Server Cluster.

Parent topic: Enterprise Server Clustering


Recovery

Depending on the failure scenario, a recovery situation can involve the planned execution of several remedial activities.
Typical activities involved in the recovery of a failed Enterprise Server Cluster include:
  • Troubleshooting a network connection that should be reactivated as soon as possible, and ideally before the connection is marked as disabled.
  • Collecting information to allow later analysis of the failure.
  • Releasing the locks held by an Enterprise Server Cluster client.
  • Restoring a database.
The main objective of any recovery process is to limit work disruption as much as possible. Disruption can be minimised by careful preparation for a cluster failure:
  • Identify the possible failure scenarios and prepare for them.
  • Ensure your preparation work is documented, and that the system administrator and/or operator knows what needs to be done at the point of failure, so that its duration is kept to a minimum.

Recovery scenarios

There are two primary causes of an Enterprise Server Cluster failure:
  • A permanent connection failure to the Global Lock Manager (GLM).
  • Catastrophic GLM failure - caused by a disk failure, memory corruption, a resource shortage etc.
Note:

The system will tolerate non-permanent connection failures for a time defined by the environment variable ES_GLM_TIMEOUT. Once the duration of a connection failure exceeds that set by this variable, the state of the connection defined between the cluster client and the GLM is marked as disabled.

At this point, any attempt to require global locks will fail and the following message is displayed in the JCL job log:
JCLCM2000E Unable to acquire global lock for job JRX0033. JCLCM0181S JOB ABENDED - COND CODE S922

The state of the connection will be reset to enabled as soon as the GLM reconnects.

Parent topic: Enterprise Server Clustering


Failure Modes

During a catastrophic GLM failure, all Enterprise Server Cluster members are dependent upon the Global Lock Manager (GLM) for the successful completion of all active jobs. In a permanent connection loss situation, system administrator actions may need to be taken on the GLM and the client.

GLM failure indicated on the Enterprise Server Cluster client

On an Enterprise Server Cluster client, GLM failure can be identified by the following console message:
CASCS1117I Connection to GLM_APPLID (sysid GLM_SYSID) lost (protocol P2P)
where:
  • GLM_APPLID is the GLM APPLID
  • GLM_SYSID is the GLM SYSID
This message indicates that the connection to the GLM has been lost. The connection may be lost because of a connection issue, but a catastrophic failure of the GLM will also result in the same message. With a catastrophic GLM failure, this connection will only be re-established after the GLM is restarted. Furthermore, with a catastrophic GLM failure, this message is returned immediately when the cluster client makes its first connection attempt. Otherwise, the system continues to retry the connection for up to the duration specified in the ES_GLM_TIMEOUT environment variable. When this limit is reached, the following console log output is displayed:
CASCS3032S Connection to ES Cluster manager ESCLMGR (sysid MST1) is disabled, verify and
release global locks on ES cluster manager.

Remedial actions

Prior to any GLM restart, it is vital that you identify and correct the reason for the failure. If necessary, you should collect CAS data for further failure analysis.

On an Enterprise Server Cluster client, active jobs can continue to execute, until they attempt to DEQUEUE their global locks. If the GLM is restarted before the DEQUEUE is requested, the DEQUEUE will execute successfully. Otherwise, the DEQUEUE will fail but the failure will be ignored and the local DEQUEUE will execute successfully. The JCL can therefore execute successfully, and no client-side actions are required.

Removing an Enterprise Server Cluster client from the cluster

Following a catastrophic GLM failure, or in the event of an Enterprise Server Cluster client failure, or some other requirement to take an Enterprise Server region out of a cluster, some action is required.

Actions to take on the GLM prior to a GLM restart
When the GLM restarts after failure, all of the cluster clients that were previously connected are now marked as ACTIVE in the CASGLM.LCK file. Consequently, the GLM will request and wait for each cluster client to send their active global locks, and places itself in the NOWORK state as it awaits the responses. This state switches back to ACTIVE as soon as the GLM has received all of the client responses. If one or more clients do not answer, the GLM cannot proceed with its work.

The NOWORK state is displayed in the GLM.

On the Server Information page of ESMAC (CASRDO5), the following state information is displayed:

When all Enterprise Server Cluster clients marked as ACTIVE in CASGLM.LCK have reconnected, the following will be displayed:

In the GLM's console log, the following message will be displayed:
CASKC6008S No reply received for lock request from ESCLSLV2. GLM work halted until reply on ESMAC
 control page is provided.
If you attempt to execute a JCL job on an Enterprise Server Cluster client while the GLM is in NOWORK state, the following sequence of messages will be displayed:
ESCL1  CASCS3036E GLM ESCLMGR (sysid MST1) is in "NOWORK" state, waiting for all ES Cluster
clients to send their locks. Check message KC6008S on the GLM. 10:36:43
ESCL1   JCLCM0188I JOB02312 LCKSLEEP JOB  STARTED 10:36:43
ESCL1   JCLCM2000E JOB02312 LCKSLEEP Unable to acquire global lock for job LCKSLEEP. 10:36:43
ESCL1   CLCM0181S JOB02312 LCKSLEEP JOB  ABENDED - COND CODE S922 10:36:43

To allow the GLM to resume lock processing, a reply is expected on the CONTROL page of the GLM's ESMAC screen (CASRDO11):

To remove the Enterprise Server Cluster client ESCLSLV2 from the cluster, uncheck the checkbox.

Lock removal following a permanent connection loss to the GLM

In the event of a permanent connection loss to the GLM, both client and GLM actions are required.

The following scenario illustrates a situation in which global lock removal is necessary.

Members of the Enterprise Server Cluster:
  • The GLM
  • Enterprise Server Cluster client 1: ESCLCLT1
  • Enterprise Server Cluster client 2: ESCLCLT2
Scenario
All members have started and have successfully completed the handshake. JCL is executing in both regions.
Client 1 state
On ESCLCLT1, JCL1 is executing in PID1 and holds exclusive locks on resource 1 and resource 2. ESCLCLT1 PID1 JCL1 is in the ACTIVE state in the active queue.
Client 2 state
On ESCLCLT2, JCL2 is executing in PID2 and requests locks for resource 1. ESCLCLT2 PID2 JCL2 is in the WAIT state in the active queue.
A permanent connection failure occurs between the GLM and ESCLCLT1. The GLM is still active and the connection between ESCLCLT2 and the GLM is active.

If during the connection failure of ESCLCLT1, JCL1 attempts to DEQUEUE its locks, the Enterprise Server Cluster client layer will retry for the duration set by ES_GLM_TIMEOUT. When this value is reached, the Enterprise Server Cluster layer will mark the connection to the GLM as disabled and all global ENQUEUE/DEQUEUE requests will be rejected. The JCL will terminate successfully, the locks - including the global locks on the Enterprise Server Cluster client - will be released, but the global locks will still be active on the GLM.

On the Enterprise Server Cluster client
The systems administrator needs to decide whether JCL1 should run to completion or if it should be cancelled.
On the Enterprise Server Cluster GLM
Whatever the decision, the locks held by JCL1 on the GLM need to be removed for the JCL2 job to run to completion on ESCLCLT2.

The next section describes the use of the caslock command and its equivalent ESMAC page (CASRDO33). Both tools provide the capability to browse and remove locks, together with the ability to take a cluster offline.

Parent topic: Enterprise Server Clustering


Lock Processing

There are several ways to browse and edit Enterprise Server Cluster locks.

When a job is submitted, it gets placed into the Input queue. If an initiator is available to run the JCL for the specified class, the job is moved to the Active queue at which point the job should execute, unless the job requires locks on files that are already locked. If this is the case, the JCL is placed into a Waiting mode.

You can browse/display the locks in the GLM and the cluster clients. When an Enterprise Server Cluster is active you may browse all global locks held on the Global Lock Manager (GLM), and you can also identify locks for a specific JCL, initiator or client. On a cluster client you can browse all the global and its own local locks. You can do this using ESMAC or via the caslock command.

Browsing active locks with ESMAC

Both GLM and Enterprise Server Cluster clients have tools to allow you to browse active locks. On the GLM, all cluster-wide global locks can be browsed. A cluster client can only display its own global locks and all of its local locks.

Browsing locks on a GLM
On the GLM, you can view all global locks and their pertinent information. A lock (ENQ) is defined by the target resources detail as well as the chain of its lock owners and the characteristics of the lock(s) they have requested.
A resource is defined by a QNAME and an RNAME:
QNAME
The QNAME defines the type of target resource for an ENQ or a DEQ. The only QNAMEs currently supported by an Enterprise Server Cluster are SYSZJOBD, SYSZJOBN and SYSZDSN.
RNAME
The RNAME defines the target resource name for an ENQ or DEQ.
The lock owner chain contains information such as:
  • Lock type - exclusive or shared.
  • Lock owner status - controlled, waiting or pending.

To view the locks on a GLM, visit the corresponding ESMAC page. In the Resources pane, select Active, then select Locks (CASRDO33). The display will resemble the following:

PID
PID of the GLM's communication server (MFCS)
res-ID
Identifies the resource ID
Type
Type of lock (shared or exclusive)
State
Lock state - Controlled, Waiting, Pending

The above screenshot illustrates a situation where job JOB01364 (jobname MYLOCK) running in a batch initiator (PID 8716) in Enterprise Server Cluster client ESCLSLV1 owns locks on several datasets, including a dataset identified by res-ID 1. In the Resource Details group, res-ID 1 is defined as belonging to Queue SYSZDSN with Resource Name SYSI.CLUSTER.MYFILE.

At the same time, job number JOB01365 (for which the job name is not yet known) running in a batch initiator (PID 12228) in Enterprise Server Cluster client ESCLSLV1 is in a wait state as it, too, requires an exclusive lock on the same resource: res-ID 1, SYSI.CLUSTER.MYFILE.

Note: In the Resource Details group, the scope is not displayed. This is because that on the GLM, all cluster-wide locks are GLM local locks.
Browsing locks on an Enterprise Server Cluster client
To view the cluster client locks, visit the corresponding ESMAC page. In the Resources pane, select Active, then select Locks (CASRDO33). The display will resemble the following, which is similar to the preceding screenshot, except that only the locks owned by this client are displayed:

Viewing active locks with the caslock command

The caslock command is self-documented - simply enter caslock -h at the Enterprise Server command prompt and the following information is displayed:
Usage: caslock [/a /l /r /u /p /c]

   /a[client_applid]        Remove locks for specified APPLID of the client region
   /l                       List all active locks
   /r[region_name]         	The name of the region to send the request to
   /u[username]             The user's username
   /p[password]             The user's password
   /c[group]                The user's group
The command: caslock -rESCLMGR -l will display all active global locks in the Enterprise Server Cluster:
Lock Ownership
PID     res-ID    Type        State         Persistence         Seq
8720    t:001    JOB01485 JRX0033  ( MYLOCK   ) (ESCLSLV1/     10392)
           1     Exclusive   Controlled    Task                 1
           2     Exclusive   Controlled    Task                 1
           3     Exclusive   Controlled    Task                 1
           4     Exclusive   Controlled    Task                 1
           5     Exclusive   Controlled    Task                 1
           6     Exclusive   Controlled    Task                 1
           7     Exclusive   Controlled    Task                 1
10660    t:002    ES Subsystem
           8     Exclusive   Controlled    Server               1
Resource Details
      res-ID     Queue        Length    Resource Name
         1      SYSZDSN           19    SYSI.CLUSTER.MYFILE
         2      SYSZDSN           20    SYSI.CLUSTER.SPEC002
         3      SYSZDSN           20    SYSI.CLUSTER.SPEC001
         4      SYSZDSN           20    SYSI.CLUSTER.PATT001
         5      SYSZDSN           20    SYSI.CLUSTER.GENE002
         6      SYSZDSN           20    SYSI.CLUSTER.GENE001
         7      SYSZJOBN           8    JRX0033
         8      SYSZJOBD           8    JRX0034
Note:
  • You can only run the caslock command against the GLM.
  • You cannot target a specific APPLID - all cluster-wide global locks are displayed.

Removing global locks

Lock removal functionality is provided to enable troubleshooting in specific circumstances. Global locks should only be removed when a permanent connection failure occurs between an Enterprise Server Cluster client and the Enterprise Server Cluster manager, and locks are held preventing jobs from executing in other cluster clients still active in the cluster.

If a connection between the GLM and one of the Enterprise Server Cluster clients has been lost for longer than the duration defined by the ES_GLM_TIMEOUT environment variable, the cluster client layer will mark the connection to the GLM as disabled. Once the client's connection state is marked as disabled it cannot be recovered. All successive attempts to connect to the cluster will be rejected with the following messages:
TXCS3032S Connection to ES Cluster manager GLM APPLID (GLM SYSID) is disabled, verify and release
 global locks on ES cluster manager
or
TXCS3033S Attempt to connect to a disabled ES Cluster manager GLM APPLID (GLM SYSID) , verify and
release global locks on ES cluster manager

The system administrator needs to take action, which must include identifying whether this region holds global locks that will prevent work units running in other active cluster clients from executing successfully. If this is the case, the system administrator needs to use ESMAC on the GLM or the caslock command to remove all the locks held by the failing Enterprise Server Cluster client.

CAUTION:
When locks are being removed, the target Enterprise Server Cluster client is implicitly removed from the cluster. Attempts to execute further JCL on this client could lead to unexpected behavior.
Removing locks with ESMAC
To remove locks with ESMAC, visit the GLM's ESMAC page. In the Resources pane, select Active, then select Locks (CASRDO33).

At the bottom of the page, the Remove Locks button will allow the removal of all the locks for an APPLID. In the client APPLID entry field, enter the APPLID of the Enterprise Server Cluster client you want to remove the locks for.

Parent topic: Enterprise Server Clustering


JCL Submission

Enterprise Server uses the equivalent of the assembler macros ENQ and DEQ. These macros provide an enqueue mechanism to serialize access to a named resource across a specified set of Enterprise Server Cluster clients in the cluster. The named resource is defined by its QNAME (major name), RNAME (minor name) and SCOPE (server or servers).

In the Enterprise Server Cluster context, global ENQs are made on three queue names only:

  • SYSZJOBD: Job dispatch (scope is always SERVERS/GLOBAL)
  • SYSZJOBN: Jobname (scope is always SERVERS/GLOBAL)
  • SYSZDSN: Dataset (scope is defined by RNLs SERVERS/GLOBAL or SERVER/LOCAL)
JCL Submission Flow in an Enterprise Server Client
In CAS manager:
  1. When a JCL is submitted, the request is written to the casspool file. This casspool is common to all Enterprise Server Cluster members.
  2. Each Enterprise Server Cluster client that has one or more initiators available for work periodically calls the Job Manager to get work for an initiator for a specific class or set of classes.
  3. JES calls the CAS manager back to check if there is already an ENQ on SYSZJOBD for this JOBNAME. ENQs on SYSZJOBD are always global and are therefore shipped to the GLM.
  4. The GLM checks if an ENQ for this JOBNAME already exists and response to the client with an appropriate return code.
  5. The Enterprise Server Cluster client CAS Manager returns the GLM response to the JOB Manager.
  6. If the return code permits execution, the batch initiator is dispatched to execute the JCL.
In the batch initiator:
  1. The job starts in the Job initiator.
  2. The JOB Manager requests an ENQ on SYSZJOBN JOBNAME. SYSZJOBN ENQ requests are always global and are therefore sent to the GLM.
  3. JES requests DEQ on SYSZJOBD JOBNAME. The DEQ is global, and therefore the request is sent to the GLM.
  4. JES requests locks for all SYSZDSN resources.
  5. RNLs are used to determine the resource's scope: SERVER/LOCAL or SERVERS/GLOBAL.
  6. If their scope is global, the SYSZDSN requests are sent to the GLM, all resources are locked locally. This means that each Enterprise Server Cluster client has a copy of its local - and more importantly - global locks.
  7. At the end of the job, JES requests the DEQ of all SYSZDSNs previously ENQueued.
  8. Global DEQs are shipped to the GLM, all SYSZDSNs are DEQueued locally.
  9. At the end of the job, SYSZJOBN JOBNAME is DEQueued.

Note: casbat is in a wait for response state until the reply comes back from the GLM.
Parent topic: Enterprise Server Clustering


RNL Support

RNLs are an IBM mainframe method used by GRS to identify resource scope. Of the RNLs functions, only those essential for identification of a SYSZDSN lock scope have been implemented.

Enterprise Server RNLs Implementation Limitations

There is no support for:
  • RNL=NO
  • GRSRNL=EXCLUDE
  • GRS=NONE
  • The ISGNQXIT or ISGNQXITFAST exit

RNLs are always used.

Enterprise Server RNLs Configuration

ESCLRNLs.cfg file characteristics
  • All RNLs must be created in a single file called ESCLRNLs.cfg.
  • This file must be located in the same folder as the CATALOG folder shared by all members of the Enterprise Server Cluster.
  • The name and location are not configurable.
  • The file ESCLRNLs.cfg is a line sequential file.
  • The file contains all the RNLDEFs to be loaded in each member of the Enterprise Server Cluster.
ESCLRNLs.cfg file processing
  1. The CAS Manager accesses the file and validates the records
  2. If the record is valid, it is dynamically installed.
  3. At the end of RNLs file processing, the following message is sent to the console:
    TXSI9024I nnn RNLDEF loaded from ESCLRNLs.cfg
    where nnn is the number of RNLs successfully loaded from the file.
If the Enterprise Server Cluster manager does not find an ESCLRNLs.cfg file, it creates a default one and adds a single line to it:
RNLDEF RNL(INCL)TYPE(GENERIC) QNAME(SYSZDSN)
This will result in the scope set to global(servers) for ALL SYSZDSN.

The file is accessed by the Enterprise Server Cluster manager only. All cluster clients will request the RNLs during the Enterprise Server Cluster client region startup. This processing is part of the handshaking executed by transaction fafaffff from the pltpi in the Enterprise Server Cluster client regions.

When RNLs have been received from the GLM, the client will send the following message to the console:
CASSI9025I All RNLDEFs received and installed from ES Cluster Manager GML_NAME

Enterprise Server RNLDEF Support Limitations

For Enterprise Server Clusters, the RNLDEFs are defined using:
An RNL identifier
  • RNL(EXCL) for the SYSTEM exclusion list
  • RNL(INCL) for the SYSTEM inclusion list
An entry type indicator
  • TYPE(SPECIFIC) - the entry is a specific name
  • TYPE(GENERIC) - the entry is a generic name
  • TYPE(PATTERN) - the entry is a pattern name
A qname
  • QNAME(QUEUE_NAME)

    Enterprise Server Clusters only process three queue names: SYSZJOBD, SYSZJOBN and SYSZDSN. RNLs are only used to define the scope of the SYSZDNS resources. SYSZJOBD and SYSZJOBN are always global (scope = servers).

An rname
  • RNAME(Resource_name)

    As the only QNAME used for RNLs is a SYSZDSN, the resource name maximum length is 44.

Enterprise Server RNLDEF Format

The mainframe allows a much looser format than the Enterprise Server Cluster implementation. See: http://publib.boulder.ibm.com/infocenter/zos/v1r12/index.jsp?topic=%2Fcom.ibm.zos.r12.ieae200%2Fiea2e2b0169.htm

In an Enterprise Server Cluster, a restricted format applies:
  • No restrictions on columns, but an RNLDEF must be contained in a single line.
  • No support for comments.
  • Each RNLDEF statement is defined as beginning with the characters RNLDEF and ends at the end of the line.
  • Each RNLDEF statement must contain, in any order, the RNL, TYPE, QNAME and RNAME parameters. The only exception to this is:
    • The RNAME parameter may be omitted it TYPE(GENERIC) is specified for a generic QNAME resource. For example:
      RNLDEF RNL(EXCL) TYPE(GENERIC) QNAME(SYSZDSN)
      This will result in the scope set to local for all SYSZDSN.
  • You can put a blank anywhere except within a keyword or a specified value.
  • There is no verification on the RNAME.
  • Formats such as RNAME(X'19') are not supported.
  • A specific resource name entry matches a search argument only when they are exactly the same. A match occurs only when the length of the RNAME value on the RNLDEF statement is the same as the length of the RNAME value coded.

RNLs Processing

The IBM diagram below illustrates RNLs processing. An Enterprise Server Cluster emulates this behavior, but note that the Enterprise Server JES subsystem never sets the scope to SERVERS (equivalent to IBM SYSPLEX or SYSTEMS value), and therefore the INCLUDE list is systematically processed. If an INCLUDE RNL matches the RNAME, the EXCLUDE list is searched.

Note that the RNLDEF processing will stop on the first match for both INCLUDES and EXCLUDES.

RNLs Examples

List of INCL/EXCL:

RNLDEF RNL(INCL) TYPE(SPECIFIC) QNAME(SYSZDSN) RNAME(SYS.CLUSTER.MYFILE)

RNLDEF RNL(INCL) TYPE(SPECIFIC) QNAME(SYSZDSN) RNAME(SYS1.CLUSTER.SPEC001)

RNLDEF RNL(INCL) TYPE(SPECIFIC) QNAME(SYSZDSN) RNAME(SYS1.CLUSTER.SPEC002)

RNLDEF RNL(INCL) TYPE(SPECIFIC) QNAME(SYSZDSN) RNAME(SYS1.CLUSTER.SPECXXX)

RNLDEF RNL(EXCL) TYPE(SPECIFIC) QNAME(SYSZDSN) RNAME(SYS1.CLUSTER.SPECXXX)

RNLDEF RNL(INCL) TYPE(GENERIC) QNAME(SYSZDSN) RNAME(SYS1.CLUSTER.GEN)

RNLDEF RNL(EXCL) TYPE(GENERIC) QNAME(SYSZDSN) RNAME(SYS1.CLUSTER.GENEXXX)

RNLDEF RNL(INCL) TYPE(PATTERN) QNAME(SYSZDSN) RNAME(SYS1.CLUSTER.PATT???)

RNLDEF RNL(EXCL) TYPE(GENERIC) QNAME(SYSZDSN) RNAME(SYS1.CLUSTER.PATTX)

RNLDEF RNL(EXCL) TYPE(PATTERN) QNAME(SYSZDSN) RNAME(SYS1.*.PAT*X2)

RNLDEF RNL(INCL) TYPE(PATTERN) QNAME(SYSZDSN) RNAME(SYS1.H???A.O*)

Parent topic: Enterprise Server Clustering


Environment variables

An Enterprise Server Cluster requires minimal configuration. The only mandatory environment variables are ES_CLUSTER, which should be set in every region that is participating as a member of a cluster, and ES_GLM, which should be set in the region designated as the Global Lock Manager (GLM).

Mandatory environment variables

ES_CLUSTER
Value: Any value sets the variable.
This environment variable should be set in every region that is participating as a member of an Enterprise Server Cluster.
ES_GLM
Value: Any value sets the variable.
This environment variable should be set in the region designated as the GLM.

Optional environment variables

ES_CLUSTER_ISC_TRACE
Value: Any value sets the variable.
This variable enables tracing on the Enterprise Server Cluster ISC listeners (no definition, dynamically created). A file called ES-Cluster-ISC-trace.txt will be created in the region's work area.
ES_CLUSTER_LISTENER_PORT_TO_USE
Value: port-number
This variable enables you to use a specific port for a listener of the cluster.
ES_NO_CLUSTER
Value: Any value sets the variable.
This variable can be used to prevent any attempt to join an Enterprise Server Cluster.
ES_GLM_TIMEOUT
Value: n seconds.
This variable only applies to the region designated as the GLM. This variable is defined in seconds and specifies the duration in which a submit request to the GLM can be retried before disabling the connection permanently. The timeout value is pushed from the GLM to all other members of the cluster.
ES_HOSTNAME_TO_USE
Value: Hostname
If the machine running an Enterprise Server uses more than one network card, you may need to set this variable to indicate to the Enterprise Server communications manager (MFCS) which hostname to use.
Parent topic: Enterprise Server Clustering


The CASGLM.LCK file

The CASGLM.LCK file stores important information about the state of an Enterprise Server Cluster.

Overview

When an Enterprise Server Cluster starts for the first time, there is no static information that defines its members. The members are dynamically added as they start, provided they have been configured to be part of such a cluster - via the ES_CLUSTER environment variable and sharing of the CATALOG.DAT and DADL.

When an Enterprise Server Cluster is started for the first time, the GLM creates a file called CASGLM.LCK in the same folder as the system catalog. At startup, cluster clients read the CASGLM.LCK file to retrieve the information stored in a specific, GLM record, of the file. Clients are then able to communicate with the GLM and send requests, so that the GLM becomes aware of them and writes a record for each cluster member.

The file also contains information used in recovery situations.

File structure

CASGLM.LCK is created in the same folder as the system catalog, and is a byte-stream file. To make it viewable, CRLF characters have been added - but it should not be updated or edited, which may lead to unexpected results. It can be deleted.

Each record is composed of six parameters:
Table 1. Structure of CASGLM.LCK records
Parameter name | Parameter value | Notes
G= or C= | GLM APPLID Cluster CLIENT APPLID | The GLM uses the client APPLID to request information such as its lock list in a recovery situation. The client uses the GLM APPLID to dynamically create and initiate an ISC listener and ISC connection to the GLM.
T= | GLM Timeout |
S= | Member SYSID | Clients use GLM SYSID to dynamically create and initiate an ISC listener and ISC connection to the GLM
A= | Y or N | Y for active, N for inactive
P= | nnnnn | Port used by the ISC listener
H= | * or the value of the environment variable: ES_HOSTNAME_TO_USE | TCP/IP address of the Enterprise Server Cluster member
The following represents sample CASGLM.LCK contents for an Enterprise Server Cluster with five members:
G=ESCLMGR  T=00060 S=MST1 A=Y P=52454 H= nwb-srv-test77
C=ESCLSLV1 T=00060 S=SLV1 A=Y P=53608 H=nwb-srv-test68
C=ESCLSLV2 T=00060 S=SLV2 A=Y P=53618 H= nwb-srv-test98
C=ESCLSLV3 T=00060 S=SLV3 A=Y P=53623 H= nwb-srv-test67
C=ESCLSLV4 T=00060 S=SLV3 A=Y P=53623 H= nwb-srv-test99
Parent topic: Enterprise Server Clustering


Tracing

ESMAC provides access to several Enterprise Server Cluster tracing facilities.

Configuring an Enterprise Server Cluster for Tracing

To configure an Enterprise Server Cluster region for tracing, go to the ESMAC home page, and note the name of your SIT - it is listed in the Startup section slightly below the middle of the main panel. Then click on SIT in the Resources group in the left-hand column, and on the next screen, click the Details button to the left of where the name of your SIT appears.

On the following screen, check the cluster trace box in the Trace Points pane:

Alternatively, from the main ESMAC page, you can enable cluster traces dynamically by clicking on the Control button towards the top of the left-hand column and checking the cluster trace box in the Trace Points pane:

Tracing Examples

Enterprise Server Cluster Client to GLM handshaking
Sending to the GLM
JCLGLM_Func(IAM)               39    9    7972 61 ad0103  9232548  <....     >  01000000 20202020
JCLGLM_Func(SNDRNLs)           41    9    7972 61 ad0103  9232687  <.... ...M>  0e000000 00001ed4
Received from the GLM
GLMRC(OK/LCKNOT/7892)          40    9    7972 61 ad0203  9232678  <.... ...M>  00000000 00001ed4
An initiator registers with the GLM
Sending to the GLM
JCLGLM_Func(CLASS)            233    5       8916 3f ad0183  9232565  <.... ....>  02000000 00000000
Received from the GLM
GLMRC(OK/LCKNOT/7892)          18    5       8916 3f ad0283  9232665  <.... ...M>  00000000 00001ed4
A JCL job requesting a global lock for SYSDSN
Cluster_SYSDSN(SYSI.CLU)       244   25       8916 02 8e1382  9454861  <SYSI .CLU>  53595349 2e434c55
Cluster_SYSDSN(STER.MYF)       245   25       8916 02 8e1382  9454861  <STER .MYF>  53544552 2e4d5946
Cluster_SYSDSN(ILE)            246   25       8916 02 8e1382  9454861  <ILE      >  494c4520 20202020
GLM_ENQ_GLOBAL                 247   25       8916 02 8e1383  9454861  <.... .   >  00000000 02202020
Parent topic: Enterprise Server Clustering


SSL Support for CICS Web Interface Servers

Setting Environment Variables

To activate SSL Support for CWI Servers, the following environment variables need to be set:
ES_CERTIFICATES_LOCATION
For CICS as an HTTP server, this should be set to the location of your server certificates.
For CICS as an HTTP client, this should be set to the location of your client certificates.
ES_DFLT_CERTIFICATE_NAME_SERVER
This should be set to the label for the certificate that CICS will use when no name has been specified in the TCPIPSERVICE for the CERTIFICATE attribute.
ES_DFLT_CERTIFICATE_NAME_CLIENT
This should be set to the label for the certificate that CICS will use if a WEB OPEN:
  • Doesn't specify the CERTIFICATE option AND
  • Doesn't specify the URIMAP option OR the specified URIMAP doesn't contain a CERTIFICATE label.

Certificate labels should be the name of the certificate file with no extension. The key file should have the same name as the certificate with _key appended, retaining its extension.

For example, if you have a certificate called srvcert.pem:
  • Name the keyfile srvcert_key.pem.
  • Set ES_DFLT_CERTIFICATE_NAME_SERVER = srvcert.
  • The folder pointed to by ES_CERTIFICATES_LOCATION will contain the following files:
    • srvcert.pem
    • srvcert_key.pem

Customizing the ESCERTPAS User Exit

To complete the SSL configuration, you also need to customize the ESCERTPAS.CBL User Exit.

ESCERTPAS is called:
  • Whenever a listener is started for an SSL-enabled TCPIPSERVICE.
  • On every WEB OPEN that uses SCHEME(HTTPS).
When an SSL listener is being started, ESCERTPAS needs to return:
  • The passphrase for the keyfile of the server certificate that is going to be used.
  • The fully-qualified CA root certificate file which contains trusted CA root certificates that were used to sign any client certificates that may use this connection (only required where the TCPIPSERVICE specified CLIENTAUTH).

On a WEB OPEN where client authentication is required, ESCERTPAS should return:

  • The passphrase for the keyfile of the client certificate that is going to be used.
  • The fully-qualified CA root certificate file which contains a trusted CA root certificate that was used to sign the server certificate for this connection.
On a WEB OPEN where client authentication is not required, ESCERTPAS only needs to return:
  • The fully-qualified CA root certificate/file which contains a trusted CA root certificate that was used to sign the server certificate for this connection.

Client certificates and CA root certificates that were used to sign server certificates will need to be added to your browser in order to be used when accessing the TCPIPSERVICE port using the HTTPS URL.

Note: The newly-compiled ESCERTPAS should replace the one shipped with the product. If you are using CICS as a web client, then this needs to happen on the client machine as well.
  • Setting up server-side SSL authentication for CWI
    To set up server-side SSL authentication for CWI, you should be capable of setting up CWI resources within Enterprise Server and also able to use the CWI APIs.
  • Setting up client-side SSL authentication for CWI
    To set up your environment for client-side SSL environments, you will again need some knowledge of CWI and the CWI CICS APIs.
  • Troubleshooting CWI SSL
    Explains purpose of topic. Written as sentence fragment. Contains no more than two sentences.
Parent topic: Enterprise Server configuration and administration


Setting up server-side SSL authentication for CWI

To set up server-side SSL authentication for CWI, you should be capable of setting up CWI resources within Enterprise Server and also able to use the CWI APIs.
A typical procedure for setting up server-side SSL authentication for CWI is as follows:
  1. Create a server certificate and sign it using the Demo CA. For details of how to do this, refer to Using the Demonstration Certificate Authority. Note that the generated keyfile should be renamed to have the same name as the certificate, with the characters _key appended, but retaining the file's original extension. For example, if the certificate and key files are srvcert.pem and srvkey.pem respectively, you should rename srvkey.pem to srvcert_key.pem.
  2. Create a TCPIPSERVICE with the following settings:
    • Status: Set to Open
    • Port no: Set to an appropriate port number.
    • SSL: Set to Yes
    • Certificate: Set to the name of your certificate - e.g. srvcert.
  3. Create a URIMAP with the following settings:
    • Usage: Set to Server.
    • Scheme: Set to Https.
    • Path: Set to your chosen URI path, for example: /my/ssl/path.
    • TCPIPService: Set to the name of the TCP service you created in step 2.
    • Decide if you want to offer a static or dynamic response by providing the details of either an HFS file or a Program.
  4. Set the value of the environment variable ES_DFLT_CERTIFICATE_NAME_SERVER to be the label/name of the server certificate that you wish to be used as the default. For example, if your certificate is called srvcert.pem, you should set the environment variable like this:
    [ES-Environment]
ES_DFLT_CERTIFICATE_NAME_SERVER=srvcert
  5. Set the value of the environment variable ES_CERTIFICATES_LOCATION to the location of your server certificates.
  6. Modify ESCERTPAS.CBL on the server machine to return the password of the server certificate's keyfile and then compile it.
    when function upper-case(lk-certificate-name) = 'SRVCERT'       *> Server certificate name
   move 'srvrootpwd'	to lk-passphrase-returned               *> Passphrase for srvcert_key.pem
   move spaces to lk-CARoot-to-be-used                          *> No client authentication
  7. Provide the client with the CA root certificate that was used to sign the server certificate.
    • If the client is a browser, then import the CA root file into the browser.
    • If the client is a CICS program, then modify ESCERTPAS.CBL on the client machine to return the fully-qualified CA root file. For example:
      when lk-certificate-name = spaces                          *> No client certificate required
  move spaces	to lk-passphrase-returned
  move ‘C:\my\path\CARootcert.pem’ to lk-CARoot-to-be-used
  8. Start your server region (and client region if using CICS as a client).
  9. From a browser, enter: https:<host>:<port number in TCPIPSERVICE>/my/ssl/path.
    Note: The host name should match the Common Name in the server certificate exactly.
  10. If the client is a CICS program then:
    • The WEB OPEN needs to specify:
      • SCHEME(HTTPS)
      • The port number specified in the TCPIPSERVICE.
    • The WEB SEND needs to specify:
      • PATH(WS-PATH) where WS-PATH has a value of '/my/ssl/path'.
  11. For information on associating client certificates with CICS user IDs, refer to User Certificate Registration for CICS Web Interface Servers.
Parent topic: SSL Support for CICS Web Interface Servers


Setting up client-side SSL authentication for CWI

To set up your environment for client-side SSL environments, you will again need some knowledge of CWI and the CWI CICS APIs.
First, you need to set your server up for server authentication as described in Setting up server-side SSL authentication for CWI.
  1. Create a client certificate and sign it using the demo CA. Note that the generated keyfile should be renamed to have the same name as the certificate, with the characters _key appended, but retaining the file's original extension. For example, if the certificate and key files are clntcert.pem and clntkey.pem respectively, you should rename clntkey.pem to clntcert_key.pem.
  2. Either modify your existing TCPIPSERVICE or create a new one, and set SSL to Clientauth in the Security section.
  3. Set the value for the environment variable ES_DFLT_CERTIFICATE_NAME_CLIENT to the label of the client certificate that you wish to use as the default. For example, if your client certificate is called clntcert.pem, you would set the environment variable as follows:
    [ES-Environment]
ES_DFLT_CERTIFICATE_NAME_CLIENT=clntcert
  4. Set the value for the environment variable ES_CERTIFICATES_LOCATION to be the location of your client certificates.
  5. Modify ESCERTPAS.CBL on the server machine to return the password for the server certificate's keyfile and the CA root file that contains the certificates(s) used to sign all client certificates that should be allowed to connect to the TCPIPSERVICE. For example:
    when function upper-case(lk-certificate-name) = 'SRVCERT'      *> Server certificate
    move 'srvrootpwd'	to lk-passphrase-returned              *> Password for srvcert_key.pem
    move ‘C:\my\path\CARootcert.pem’ to lk-CARoot-to-be-used   *> CA root used to sign client certificates
  6. If your client is a browser, convert your client certificate and private key into a suitable format and import it into the browser. For example, to convert a PEM certificate file and private key to PKCS#12:
    openssl pkcs12 -export -out clntcert.pfx -inkey clntcert_key.pem -in clntcert.pem
  7. If your client is a CICS program then modify ESCERTPAS.CBL on the client machine to return the passphrase for the client key file and the fully-qualified CA Root certificate file (containing the certificate used to sign the server certificate). For example:
    when function upper-case(lk-certificate-name) = 'CLNTCERT'              *> Client certificate
    move ‘myclientpwd’ to lk-passphrase-returned                        *> Password for clntcert_key.pem
    move ‘C:\my\path\CARootcert.pem’ to lk-CARoot-to-be-used            *> CA root used to sign server certificate
  8. Start your server region (and client region if using CICS as a client).
  9. From a browser enter: https://<host>:<port number in TCPIPSERVICE>/my/ssl/path Note that the host name should match the Common Name in the server certificate exactly. You should be prompted to choose a client certificate to use.
  10. If the client is a CICS program:
    • The WEB OPEN should specify:
      • SCHEME(HTTPS)
      • The port number specified in the TCPIPSERVICE.
      • CERTIFICATE(WS-CERT) where WS-CERT has a value of clntcert. If no certificate is specified, then the default client certificate is used. You can also specify a URIMAP on the WEB OPEN which specifies which certificate to use.
    • The WEB SEND should specify:
      • PATH(WS-PATH) where WS-PATH has a value of /my/ssl/path.
Parent topic: SSL Support for CICS Web Interface Servers


Troubleshooting CWI SSL

If you are having problems setting up CWI SSL, it can be useful to test your certificates completely separately from Enterprise Server. For example, you can check the contents of a certificate with the openssl command:
openssl x509 -in file.pem -noout -text
You can also use openssl s_server and openssl s_client as simple SSL servers and clients to verify that there aren't any problems with your certificates.

TCPIPSERVICE startup failures

If your server certificates are valid and you are having problems starting up a TCPIPSERVICE then check in the console log for failure messages. Possible messages and suggested corrective actions include:

CASSI1010W Error environment variable ES_CERTIFICATES_LOCATION not set or pointing to an invalid location
Ensure that the environment variable ES_CERTIFICATES_LOCATION is set and pointing at a valid location.
CASSI1011W TCPIPSERVICE <TCPIPSERVICE name> could not be started. Certificate <server certificate> could not be found
Ensure that the server certificate filename (excluding the extension) matches the certificate label specified in the TCPIPSERVICE and is in the directory referenced by the value of the ES_CERTIFICATES_LOCATION environment variable. If a certificate is not specified in the TCPIPSERVICE, then the server certificate filename should match the value of the environment variable ES_DFLT_CERTIFICATE_NAME_SERVER.
CASSI1012W Error no certificate specified for TCPIPSERVICE <TCPIPSERVICE name> and ES_DFLT_CERTIFICATE_NAME_SERVER not set
Ensure that a server certificate is specified in the TCPIPSERVICE or by the environment variable ES_DFLT_CERTIFICATE_NAME_SERVER. Do not specify the file extension for the certificate.
CASSI1013W Error TCPIPSERVICE <TCPIPSERVICE name> could not be started. No passphrase for server certificate <server certificate>
Ensure that ESCERTPAS.CBL returns the passphrase for the server certificate key file when the server certificate is provided as input. ESCERTPAS.CBL should be compiled and replace the binary distributed with the product.
CASSI1014W No CA root file provided to validate client certificates for TCPIPSERVICE <TCPIPSERVICE name>. Server certificate is <server certificate>
This message doesn't imply that a TCPIPSERVICE failed to start. It simply means that client authentication cannot take place - which may be what you intended.
CASSI1015W TCPIPSERVICE <TCPIPSERVICE name> could not be started. Keyfile <server certificate key file> could not be found
Ensure that the server key file has the same name as the server certificate with _key appended, while retaining the file extension, and that it resides in the directory referenced by the value of the environment variable ES_CERTIFICATES_LOCATION.

If the TCPIPSERVICE fails to start and none of the above messages are received, then ensure that the port specified in the TCPIPSERVICE is not already in use. You should also check the log.html file in the system directory for any errors.

WEB OPEN failures

If you experience WEB OPEN failures, you should work through the following checklist:
  • Ensure that the TCPIPSERVICE on the server that is the target of the WEB OPEN is open.
  • Ensure that ESCERTPAS on the client machine will return the fully-qualified CA root file that contains the certificate used to sign the server certificate. In this case, the input certificate to ESCERTPAS will either be the client certificate being used on this WEB OPEN or spaces if no client certificate is being provided.
  • If the target TCPIPSERVICE requires client authentication, ensure that:
    • Either a client certificate is specified on he WEB OPEN (explicitly or in the URIMAP if one is specified) or ES_DFLT_CERTIFICATE_NAME_CLIENT is set to the name of your client certificate (without the file extension) on your CICS client machine.
    • The value for ES_CERTIFICATES_LOCATION on your CICS client machine is set to the directory which contains your client certificate.
    • The client certificate has a key file with the same name with _key appended, and it resides in the same directory as the client certificate.
    • ESCERTPAS on your CICS client machine will return the passphrase for the client certificate key file when the client certificate name is provided as input.
    • ESCERTPAS on your CICS server machine must have returned a full-qualified CA root file which contains a certificate used to sign the client certificate being used on this WEB OPEN when the TCPIPSERVICE started up. In this case, the server certificate would have been the input to ESCERTPAS.
If there are still problems, check log.html for further errors.

Browser failures

Most browser failures are caused by certificate problems.
  • Ensure that the CA root certificate used to sign the server certificate has been installed in the browser.
  • If the target TCPIPSERVICE requires client authentication, ensure that your client certificate has been installed in your browser.

Diagnostics

If you are experiencing further CWI SSL issues and have exhausted the above options, there are several ways in which you can collect diagnostics to help you understand the problem:
  • The console log will show warning messages if any TCPIPSERVICE failed to open at region startup.
  • The communications log - log.html - is a good place to check if something doesn't seem to be working properly.
  • CCI tracing can be used to collect some SSL traces. Create a CCI.INI file and copy it to the current directory of the MFCS process. On Windows this is usually %WINDIR%, on UNIX you can use /prog/pid/cwd with the PID of the mfcs32 process:
    [ccitcp-base]
ssl_display_options_on=yes
ssl_display_cert_connection_details=yes
ssl_display_destination=c:\tmp\cci-ssl-info.txt
    You can also use CCI.INI to enable CTF tracing for CCI, in conjunction with the usual CTF configuration file. The CCI.INI section would look like:
    [ccitrace-base]
force_trace_on=yes
data_trace=no
protocol_trace=yes
internal_net_api=yes
    and the CTF configuration file would include:
    mftrace.dest=binfile
mftrace.emitter.binfile#Location = path
mftrace.emitter.es#level = 99999
mftrace.level.mf.cci = info
    Finally, you would set your MFTRACE environment variable to point to the CTF configuration file.
Parent topic: SSL Support for CICS Web Interface Servers


User Certificate Registration for CICS Web Interface Servers

Web servers created using the CICS Web Interface (CWI) feature of Enterprise Server can be configured to use the Secure Sockets Layer (SSL) for communications security. Along with enabling SSL, you can specify the CLIENTAUTH option to allow clients to send user certificates to the server, and one of the various AUTHENTICATE options to tell CWI how to handle user authentication. If you specify CLIENTAUTH and one of the CERTIFICATE, AUTOREGISTER or AUTOMATIC options, your CWI server will use the Enterprise Server user certificate registration mechanism. This section explains user certificate registration and what you can do with it.

  • Understanding User Certificate Registration
    In SSL, clients and servers can identify themselves using X.509 certificates.
  • User Certificates for CICS Web Services
    If you want to use client certificates with CWI, you can issue personal certificates to your users, or issue system certificates for their computers, or use certificates from multiple sources.
  • Registering User Certificates
    A client certificate can be associated with a CICS user ID, or registered, in two ways.
  • Configuration and Administration
    CICS Web Interface user certificate registrations are maintained as a collection of text files, one per registered certificate.
  • cascertreg
    Use the cascertreg command-line utility to list, delete, or add certificate registrations for CICS Web Interface servers.
Parent topic: Enterprise Server configuration and administration


Understanding User Certificate Registration

In SSL, clients and servers can identify themselves using X.509 certificates.

X.509 certificates are digitally-signed binary documents. A certificate contains information about the thing (a person, a computer, or anything else that can be given a name) it identifies - the subject. This information includes its name, where it's located, and a public encryption key that can be used to encrypt data for the subject, or verify the subject's digital signature. The certificate is signed by an issuer - usually a Certificate Authority (CA) - who is vouching for the subject's authenticity. If one side of an SSL transaction (the client or the server) sends a certificate, the other side can validate that certificate and decide whether it trusts the user; if the certificate is invalid or the recipient doesn't trust the issuer, the conversation is terminated.

When SSL is used with HTTP (HTTPS), typically only the server sends a certificate. The client checks the certificate against a list of trusted CAs (also known as trusted roots), and performs some other checks in order to decide whether it's talking to the server it wanted to connect to. This helps prevent an attacker from impersonating the server.

It is also possible to have the client program (which may be a web browser, an application invoking a web service etc.) send a certificate, which identifies it to the server. This can provide additional security without making users send usernames and passwords or otherwise proving their identity.

CICS supports user sign-on with certificates for CWI servers.

Parent topic: User Certificate Registration for CICS Web Interface Servers


User Certificates for CICS Web Services

If you want to use client certificates with CWI, you can issue personal certificates to your users, or issue system certificates for their computers, or use certificates from multiple sources.

This sort of certificate has a subject distinguished name like C=US, ST=Maryland, L=Rockville, O=Micro Focus, CN=John Doe.

In some applications, the certificate sent by a client program to identify a user must be a certificate that is actually issued in the user's name - sometimes called a personal certificate. However, the CICS Web Interface does not require that a user be identified by a personal certificate. With CWI, a client can supply any certificate that CICS will accept (following the rules listed below), and that certificate can be associated with a user ID. For example, some users might obtain personal certificates from public issuers such as Verisign.

When client certificates are used, Enterprise Server assumes that the region is configured with an external security manager. Note that if external security is not used, certificates can be registered (associated with a CICS user) even when invalid users/passwords are specified. The certificate will remain associated with that user even if security is subsequently switched on (and hence there will be no further validation for that user/certificate combination).

Registrations can be deleted by using the cascertreg utility

Certificate acceptance

For CWI to accept a client certificate, the following must be true:
  • The certificate must have an issuing timestamp before the current time and date, and an expiration date later than the current time and date.
  • It must be unaltered, since it's a digitally-signed document.
  • It must be signed by a certification authority (CA, also known as a root certificate) that is recognized by CICS, so that CICS can verify the certificate's signature.
  • It must be created using cryptographic algorithms recognized by CICS. Micro Focus uses a recent version of OpenSSL to process certificates and should recognize all algorithms that are in widespread use.
  • The client must know the private key associated with the certificate. This proves the client (and by assumption, the user) is authorized to use the certificate. In practice, this means the user will at some point provide a passphrase that decrypts the private key. With some client software, the user's private key is automatically decrypted when the user signs on to the operating system; in other cases, the user will be prompted to provide a passphrase before the certificate can be used.

Client certificates can be purchased from commercial CAs such as Verisign. They can also be generated using a variety of tools, including the DemoCA utilities included with some Micro Focus products.

Parent topic: User Certificate Registration for CICS Web Interface Servers


Registering User Certificates

A client certificate can be associated with a CICS user ID, or registered, in two ways.

First, an administrator can use the Micro Focus CICS Web Interface certificate registration utility, cascertreg, to register a certificate. All the administrator needs for this purpose is a copy of the certificate file (in PEM or DER format) or the certificate's SHA-1 'fingerprint'. This process is described in more detail in the section on the cascertreg command.

The other way to register certificates is to let CWI do it automatically. This is enabled by specifying the AUTOREGISTER or AUTOMATIC option when configuring an SSL-enabled CWI server (along with CLIENTAUTH, which is necessary to use client certificates in the first place).

With AUTOREGISTER/AUTOMATIC, when a client sends a client certificate, CWI will validate it and then look to see if it is registered. If it is, the user ID associated with it will be used for the CWI transaction and no further input from the user is required. If the certificate is not registered however, CWI will prompt the user to sign in - using the standard HTTP mechanism, so with a browser, you will typically see a username/password dialog). If the user supplies a valid CICS user ID and password, the certificate will be registered for that user. For more information, consult the IBM CICS Internet Guide (SC34-8425).

Parent topic: User Certificate Registration for CICS Web Interface Servers


Configuration and Administration

CICS Web Interface user certificate registrations are maintained as a collection of text files, one per registered certificate.
By default, these files are located in a directory named cwi-user-certs under the region's system directory (where log files are located), but you can change this by adding the following setting to the Configuration Information area of the General tab of the server's definition in Enterprise Server Administration.
[CWI]
User certificate registry=path to directory

Each registration file is named by the SHA-1 fingerprint of the certificate it represents, which is a string of hexadecimal digits that uniquely identifies a certificate. The contents are in ini-file format, and contain a single section, also named by the fingerprint, together with a line assigning a user ID to the 'user' token. There may also be some comments regarding the creation of the registration.

Note: If you use CWI with certificate registration, it is very important that only trusted administrators have write access to these files and the directory containing them. Anyone with write access to the files or directory can potentially impersonate any CICS user when running CWI-spawned transactions. Assign appropriate operating-system file permissions when creating the certificate registration directory.

These files can be edited and deleted manually, and it is possible to create them if you have some understanding of certificates and access to a tool such as OpenSSL. Normally, however, the files are created either by Enterprise Server (using AUTOREGISTER, as described in a previous section) or with the cascertreg utility.

Deleting a certificate registration file will force the owner of that certificate to re-register the first time the certificate is used, after the region has been restarted. Currently, there is no way to instruct a running region to remove a registration it has already loaded from the directory.

Parent topic: User Certificate Registration for CICS Web Interface Servers


cascertreg

Use the cascertreg command-line utility to list, delete, or add certificate registrations for CICS Web Interface servers.

Syntax:

cascertreg [common-options] command [command-options] [parameters]

Common options:

-directory path | Specify the certificate registration directory. You can also specify this by setting the ES_CERT_REG environment variable.
-nobanner | Do not display the banner (program name and copyright message).
-quiet | Provide minimal output - do not ask for confirmation when deleting registrations.
-verbose | Provide more output.

Commands, Command Options and Parameters:

Command | Options | Parameters | Explanation
list |  | partial fingerprint (optional) | List certificate registrations. If a partial fingerprint is supplied, only list certificates that match.
delete |  | partial fingerprint (optional) | Delete certificate registrations (matching the partial fingerprint if supplied). Will list matching registrations and prompt for confirmation unless -quiet is specified.
add | -file certificate-file or -fingerprint fingerprint | User ID | Add a registration for the specified certificate (supplied as either the certificate file or its fingerprint), associating it with the specified user. Will fail if a registration for the certificate already exists. With the -file option, the certificate must be in PEM or DER format.

Examples

List all the certificate registrations in the specified directory. The list will show fingerprints and user IDs.
cascertreg -directory c:\cwi-certs list

List all certificate registrations in the directory specified by the ES_CERT_REG environment variable that include the string 01ab in their fingerprints. The list will be in verbose form, showing any additional information recorded in the registration (such as subject and issuer Distinguished Names).
cascertreg list -verbose 01ab

Delete any registrations in the specified directory that include the string 01ab in their fingerprints, without prompting for information.
cascertreg -quiet delete 01ab -directory c:\cwi-certs

Add a registration (to the directory specified by the ES_CERT_REG environment variable) for the certificate in client.pem, associating it with the SYSAD and user ID.
cascertreg add -file client.pem SYSAD
Parent topic: User Certificate Registration for CICS Web Interface Servers


Configuring Client-Server Communications

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

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

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
    • TN3270 for requests from TN3270 terminals
    • MSS Inter-System Communication, MSS Inter-System Communication (inbound only) and CICS Transaction Gateway for CICS Intersystem Communication (peer-to-peer) and for requests for CICS transactions from non-CICS programs
    • Custom for any other type of requests

    TN3270 and the MSS ISC types are only available for use with MSS.

  • 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

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin and \bin64 . 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

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

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
[ezasoket]
exclusive-bind=bind-setting
select-poll-interval=time-in-milliseconds
share descriptors=share-setting
[ISC]
listener-wait=listener-wait-number-of-seconds
[listeners]
logging=logging-level
[MFCC]
trace=trace-setting
[tasks]
maximum latency=time-in-seconds
mutex sweep enabled=yes-or-no
thread limit=number-of-pool-threads
trace=trace-level
wait queue sweep interval=time-in-seconds
[threading]
limit=number-of-threads

The sections, settings and their parameters are explained below.

  • [CCI] section
  • [ezasoket] Section
  • [ISC] Section
  • [listeners] Section
  • [MFCC] Section
  • [tasks] Section
  • [threading] Section
Parent topic: Configuring Communications Processes


[CCI] section

  • timeout-grain
    Specifies the CCI timeout in seconds. Any MFCS timeout will be rounded up to a multiple of this value.
Parent topic: Editing Communications Settings


timeout-grain

Specifies the CCI timeout in seconds. Any MFCS timeout will be rounded up to a multiple of this value.

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: [CCI] section


[ezasoket] Section

This section enables you to specify options for Mainframe Subsystem EZ Sockets processing.

  • exclusive-bind
  • select-poll-interval
    Specifies the time in milliseconds between the checks for taken sockets and posted ECBs in the SELECTEX function.
  • share descriptors
Parent topic: Editing Communications Settings


exclusive-bind

Restriction:
  • This option only applies in Windows environments.
  • These options apply only when the Enterprise Server feature is enabled.

Syntax:

exclusive-bind=on|off

Parameters:

Off
Use the normal Winsock semantics for BIND which lets one application bind a port even if the port is already in use.
On
Specifies that the BIND semantics of the mainframe, and every other non-Windows platform, are in effect and BIND will be rejected ports that are already in use.

Properties:

Default: on
Parent topic: [ezasoket] Section


select-poll-interval

Specifies the time in milliseconds between the checks for taken sockets and posted ECBs in the SELECTEX function.
Note: The first few checks happen at shorter intervals so that fast-running systems will not be excessively delayed when making GIVESOCKET or TAKESOCKET calls.

Syntax:

select-poll-interval=milliseconds

Properties:

Default: 1000
Parent topic: [ezasoket] Section


share descriptors

By default, each application has a private collection of socket descriptors. The application receives socket number 0 from its first call to a function that returns a descriptor, such as SOCKET.

If share-setting is Yes or 1, all applications in the region will instead have a common set of descriptors. This means that applications can share sockets without using a GIVESOCKET or a TAKESOCKET call. This emulates the behavior in a mainframe CICS region. It, however, does not emulate the behavior of applications running under JCL.

Note: Enabling this option requires that your applications explicitly close all sockets when they are done with them. The sockets will not be implicitly closed by TERMAPI or the application exit.

Syntax:

share descriptors=share-setting

Parameters:

share-setting
Can be one of:
1 or Yes
Configures all applications in the region to have a common set of descriptors.
No
The default setting.

Properties:

Default: No
Parent topic: [ezasoket] Section


[ISC] Section

  • listener-wait (MSS only)
    Specifies how many seconds to wait for a local ISC listener to become available when starting an ISC outbound connection to connect to another MSS instance or other ISC-compatible system.
Parent topic: Editing Communications Settings


listener-wait (MSS only)

Syntax:

listener-wait=listener-wait-number-of-seconds

Properties:

Default: 10 seconds

Comments:

MFCS needs to have an ISC listener available to support outbound ISC communications. This is most useful if you have outbound ISC connections configured at startup.

Parent topic: [ISC] Section


[listeners] Section

  • logging
    Enables additional logging when starting listeners.
Parent topic: Editing Communications Settings


logging

Enables additional logging when starting listeners.

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

Properties:

Default: 0
Parent topic: [listeners] Section


[MFCC] Section

  • trace
    Controls common client (MFCC) tracing, in conjunction with the MFCC configuration file.
Parent topic: Editing Communications Settings


trace

Controls common client (MFCC) tracing, in conjunction with the MFCC configuration file.

Syntax:

trace=trace-setting

Parameters:

trace-setting
One of:
0
Disables MFCC tracing
any non-zero value
Enables MFCC tracing during MFCS startup

Properties:

Default: 0

Comments:

MFCC tracing is off by default but can be enabled in the configuration file. By default, this is mf-client.dat, located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin and \bin64 , 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: [MFCC] Section


[tasks] Section

  • maximum latency
    Specifies the time (in seconds) that a runnable task has to wait for a free thread in the worker pool before MFCS attempts to start an additional temporary thread to process it.
  • mutex sweep enabled
    When set to "no" disables the end-of-task mutex sweep.
  • thread limit
    Sets the number of threads in the task thread worker pool.
  • trace
    Sets the MFCS Task Manager trace level.
  • wait queue sweep interval
    The time (in seconds) between checking whether any tasks on the "wait queue" are runnable.
Parent topic: Editing Communications Settings


maximum latency

Specifies the time (in seconds) that a runnable task has to wait for a free thread in the worker pool before MFCS attempts to start an additional temporary thread to process it.

Syntax:

maximum latency=time-in-seconds

Properties:

Default: 3 seconds

Comments:

For enterprise servers that normally have a relatively light load and only occasionally experience peaks of activity (for example, at the beginning of the day when users start working), you may want to decrease the value of the maximum latency to enable MFCS to start temporary threads faster.

If users can tolerate a slightly longer waiting times, it may be useful to increase the value of the maximum latency as this helps avoid starting extra threads that consume system resources.

Parent topic: [tasks] Section


mutex sweep enabled

When set to "no" disables the end-of-task mutex sweep.

Syntax:

mutex sweep enabled=yes-or-no

Properties:

Default: yes

Comments:

This sweep is a defensive measure that is normally performed at the end of each task. It checks to verify that the task does not end with any mutexes locked. A locked mutex at that point can only be the result of a logic error. The sweep ensures that such an error does not block the processing of any new requests.

Normally, it is not recommended to change this setting. In cases when there is a very busy enterprise server instance, however, the sweep may cause MFCS to fall behind in task processing, causing a gradual drop in throughput. In such cases, you can set this to "no" to try to alleviate the problem.

Parent topic: [tasks] Section


thread limit

Sets the number of threads in the task thread worker pool.

Syntax:

thread limit=number-of-pool-threads

Properties:

Default: 10

Comments:

Typically, there is one (or, sometimes, two) task per conversation that is actively doing work: processing a request, sending or receiving data, and so on. This task is performed by threads in the worker pool.

If all pool threads are busy, any new tasks have to wait either until a pool thread is available or until the maximum task latency is reached for the oldest waiting task, when MFCS adds temporary threads to the pool.

If there are frequent messages in the MFCS log about adding temporary threads to the pool, you can increase the thread limit value in order to make the pool larger at startup. Generally, the pool should be as large as the total number of requests you expect the enterprise server to be processing at once - so this needs to be about one to two times the number of SEPs.

Parent topic: [tasks] Section


trace

Sets the MFCS Task Manager trace level.

Syntax:

trace=trace-level

Properties:

Can be one of 0 (no tracing) to 4 (currently, the most verbose tracing). Values above 1 can produce a lot of trace messages.
Default: 0

Comments:

Trace messages are written to the MFCS log.

Parent topic: [tasks] Section


wait queue sweep interval

The time (in seconds) between checking whether any tasks on the "wait queue" are runnable.

Syntax:

wait queue sweep interval=time-in-seconds

Properties:

Default: 15 seconds

Comments:

The "wait queue" is for tasks that cannot be processed yet because they require resources that are being used by another task. Normally, tasks are moved from the "wait queue" to the "run queue" automatically when the task that was blocking them finishes. A sweep is performed only to ensure that no tasks on the "wait queue" are forgotten.

Usually, there is no need to change this setting.

Parent topic: [tasks] Section


[threading] Section

  • limit
    Specifies the thread limit.
Parent topic: Editing Communications Settings


limit

Specifies the thread limit.

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.

Starting with MFCS version 2.0, MFCS no longer requires one thread for each active conversation. Because of this, so it is rarely necessary to change this value. For more details, see the topic on the thread limit setting in the [tasks] section.

Note that the operating system might not allow MFCS to actually create as many threads as the number you set.

Parent topic: [threading] Section
Related reference
thread limit


To Edit a Communications Process

  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

  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

  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

  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

  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

  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

  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

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
  • TN3270 conversation type
  • TN3270E conversation type
  • MSS Inter-System Communication conversation type
  • MSS Inter-System Communication (inbound only) conversation type
  • CICS Transaction Gateway conversation type
Parent topic: Configuring Client-Server Communications


Web Services and J2EE conversation type

There are no settings for this conversation type.

Parent topic: Configuring Listener Conversation Types


Web conversation type

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.

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.

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.

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.

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

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
synchronous=Yes
[Trace]
control=control-flow-trace
data=data-trace
file=pathname
  • 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.
  • synchronous
    Specifying this option reduces the latency (the time it takes to get a response) for Fileshare clients using this listener.
  • timeout
    Sets the timeout, in seconds, for receiving data from the client.
Parent topic: Configuring Listener Conversation Types


control

Enables the tracing of control flow in the connector.

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.

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.

Syntax:

file=pathname

Properties:

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


synchronous

Specifying this option reduces the latency (the time it takes to get a response) for Fileshare clients using this listener.

The option also increases the resource use and reduces scalability, particularly the maximum number of connected clients, in the MFCS process. It may not offer a significant benefit if there are many clients making simultaneous requests.

Syntax:

synchronous=yes|Yes|y|Y|1
Parent topic: Fileshare conversation type


timeout

Sets the timeout, in seconds, for receiving data from the client.

Syntax:

timeout=number-of-seconds

Properties:

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


TN3270 conversation type

The TN3270 connector checks the settings below periodically; changes affect current and new conversations.

[logging]
client-close=client-close-logging
[Operation]
default-terminal-type=terminal-type-name
Timeout=number-of-seconds
TN3270E=negotiation-type
[Trace]
trace=control-flow-trace
data=data-trace
length=trace-length
sem=send-semaphore-trace
file=trace-filename
  • client-close
    Controls the logging of client disconnection.
  • default-terminal-type
    Overrides an invalid terminal type sent by the client.
  • Timeout
    Specifies the receive timeout, in seconds.
Parent topic: Configuring Listener Conversation Types


client-close

Parameters:

client-close-logging If this is set to “yes”, log normal client disconnection

Properties:

Default: Log only abnormal client disconnection
Parent topic: TN3270 conversation type


default-terminal-type

Parameters:

terminal-type-name A valid terminal-type name, for example, “ibm-3278-2”

Properties:

Default: None

Comments:

TN3270 conversation negotiation includes the client telling the server what terminal type it is emulating. TN3270E specifies a set of allowed terminal types, but classic TN3270 has less strict requirements, and even some TN3270E clients do not conform to the specification. When the connector receives an illegal terminal type, it normally asks the client to specify a different one, but some clients (for example NetManage ViewNow) do not respond correctly. In this case you are advised to provide this setting.

Parent topic: TN3270 conversation type


Timeout

Syntax:

Timeout=number-of-seconds

Properties:

Default: 84600 seconds (one day)
Parent topic: TN3270 conversation type


TN3270E conversation type

Syntax:

Disables TN3270E (Enhanced TN3270) negotiation.

TN3270E=negotiation-type

Parameters:

negotiation-type Set to “no” to disable TN3270E negotiation

Properties:

Default: Enhanced TN3270 negotiation is enabled

Comments:

Currently required for some NetManage terminal emulator products, such as ViewNow 1.0 Host Access Quick Connect 3270.

  • trace
    Enables the tracing of control flow in the connector.
  • data
    Enables data tracing.
  • length
    Specifies the maximum number of data bytes to include in the data trace.
  • sem
    Enables the tracing of operations on the send semaphore.
  • file
    Specifies the full path of the file to receive trace messages. The file is written as HTML (unlike the Fileshare and ISC traces).
Parent topic: Configuring Listener Conversation Types


trace

Syntax:

trace=control-flow-trace

Parameters:

control-flow-trace Set to “yes” to enable control flow tracing

Properties:

Default: Tracing is disabled
Parent topic: TN3270E conversation type


data

Syntax:

data=data-trace

Parameters:

data-trace
Can be one of:
yes or all
Trace all data flows
nvt
Trace data flows only in NVT mode (which essentially means only during negotiation)
any other value
Disable data tracing

Properties:

Default: Tracing is disabled
Parent topic: TN3270E conversation type


length

Syntax:

length=trace-length

Properties:

Default: 40 bytes
Parent topic: TN3270E conversation type


sem

Syntax:

sem=send-semaphore-trace

Parameters:

send-semaphore-trace Set to “yes” to trace operations on the send semaphore

Properties:

Default: Tracing is disabled

Comments:

This setting might be useful useful when problems with the send semaphore are suspected, for example, because conversations seem to hang but ESMAC does not show them as busy.

Parent topic: TN3270E conversation type


file

Syntax:

file=trace-filename

Properties:

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


MSS Inter-System Communication conversation type

Only one listener with this conversation type can be active for a region. To create others, use the MSS Inter-System Communication (inbound only) or the CICS Transaction Gateway types depending on your requirements.

[Operation] changes take effect for the conversations that commence after you make changes, but not for the current conversation.

[Trace] changes take effect for both new and existing conversations.

[Operation]
timeout=number-of-seconds
[Trace]
trace=control-flow-trace
data-trace=data-trace-setting
allmax=dump-size
file=pathname
  • timeout
    Sets the timeout, in seconds, for receiving data from the client.
  • trace
    Enables the tracing of control flow in the connector.
  • data-trace
    Enables the tracing of sent and received data.
  • allmax
    If data-trace is set to “all”, sets the maximum number of bytes to include in the user data dump.
  • file
    Specifies the full path of the file to receive trace messages. The file is plain text.
Parent topic: Configuring Listener Conversation Types


timeout

Syntax:

timeout=number-of-seconds

Properties:

Default: Timeout for the communications process, which is 7200 seconds (two hours)
Parent topic: MSS Inter-System Communication conversation type
Parent topic: MSS Inter-System Communication (inbound only) conversation type
Parent topic: CICS Transaction Gateway conversation type


trace

Syntax:

trace=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: Tracing is disabled
Parent topic: MSS Inter-System Communication conversation type
Parent topic: MSS Inter-System Communication (inbound only) conversation type
Parent topic: CICS Transaction Gateway conversation type


data-trace

Syntax:

data-trace=data-trace-setting

Parameters:

data-trace-setting
Can be one of:
no
Do not trace data flows
header
Create formatted trace of CTG protocol headers
fmh or structure
Create formatted trace of CTG headers and request and response headers
all
Create formatted trace of headers and dump of user data
dump
Create unformatted dump of all data

Properties:

Default: Tracing is disabled
Parent topic: MSS Inter-System Communication conversation type
Parent topic: MSS Inter-System Communication (inbound only) conversation type
Parent topic: CICS Transaction Gateway conversation type


allmax

Syntax:

allmax=dump-size

Parameters:

dump-size Set to 0 (unlimited) if you want to include all the data

Properties:

Default: Unlimited, that is, include all the data.
Parent topic: MSS Inter-System Communication conversation type
Parent topic: MSS Inter-System Communication (inbound only) conversation type
Parent topic: CICS Transaction Gateway conversation type


file

Syntax:

file=pathname

Properties:

Default: Trace messages are written to the MFCS log (as HTML).
Parent topic: MSS Inter-System Communication conversation type
Parent topic: MSS Inter-System Communication (inbound only) conversation type
Parent topic: CICS Transaction Gateway conversation type


MSS Inter-System Communication (inbound only) conversation type

Describes the MSS Inter-System Communication (inbound only) listener type.

This conversation type is used for MSS ISC listeners other than MF MTO Inter-System Communication.

[Operation] changes take effect for the conversations that commence after you make changes, but not for the current conversation.

[Trace] changes take effect for both new and existing conversations.

[Operation]
timeout=number-of-seconds
[Trace]
trace=control-flow-trace
data-trace=data-trace-setting
allmax=dump-size
file=pathname
  • timeout
    Sets the timeout, in seconds, for receiving data from the client.
  • trace
    Enables the tracing of control flow in the connector.
  • data-trace
    Enables the tracing of sent and received data.
  • allmax
    If data-trace is set to “all”, sets the maximum number of bytes to include in the user data dump.
  • file
    Specifies the full path of the file to receive trace messages. The file is plain text.
Parent topic: Configuring Listener Conversation Types


CICS Transaction Gateway conversation type

This conversation type is used for MSS ISC listeners other than MF MSS Inter-System Communication that do not use the Legacy Micro Focus Application format.

[Operation] changes take effect for the conversations that commence after you make changes, but not for the current conversation.

[Trace] changes take effect for both new and existing conversations.

[Operation]
timeout=number-of-seconds
[Trace]
trace=control-flow-trace
data-trace=data-trace-setting
allmax=dump-size
file=pathname
  • timeout
    Sets the timeout, in seconds, for receiving data from the client.
  • trace
    Enables the tracing of control flow in the connector.
  • data-trace
    Enables the tracing of sent and received data.
  • allmax
    If data-trace is set to “all”, sets the maximum number of bytes to include in the user data dump.
  • file
    Specifies the full path of the file to receive trace messages. The file is plain text.
Parent topic: Configuring Listener Conversation Types


Configuring Listeners

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

  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
    • TN3270 for requests from TN3270 terminals
    • MSS Inter-System Communication for CICS Intersystem Communication (peer-to-peer) and for requests for CICS transactions from non-CICS programs. This conversation type handles both inbound and outbound calls. Only one listener of this type can be used with an enterprise server. The corresponding conversation type in previous Enterprise Server software releases is Micro Focus MTO Inter-System Communication.

      This conversation type uses Legacy Micro Focus Application Format.

    • MSS Inter-System Communication (inbound only) is similar in functionality to the MSS Inter-System Communications conversation type. The corresponding conversation type in previous Enterprise Server software releases is the MSS ISC type that did not have a name of Micro Focus MTO Inter-System Communciations.

      This conversation type uses Legacy Micro Focus Application Format.

    • CICS Transaction Gateway is similar in functionality to the previous two conversation types, except that it does not use Legacy Micro Focus Application Format.
    • 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
Parent topic: Common Configuration Tasks


To Edit a Listener

  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

  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

  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

  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

  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

  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


Configuring Enterprise Server for IBM WebSphere MQ

Typically, configuring Enterprise Server for WebSphere MQ involves defining an XA resource. In addition, if you require triggering, you will need to define a WebSphere MQ listener. The way you do this depends on your environment.

  • CICS and WebSphere MQ
    Details how to configure Enterprise Server for CICS under WebSphere MQ.
  • IMS and WebSphere MQ
    Details how to configure Enterprise Server for IMS under WebSphere MQ.
  • JCL Programs and WebSphere MQ
    Details how to configure Enterprise Server for JCL programs under WebSphere MQ.
  • Non-Mainframe Programs and WebSphere MQ
    Details how to configure Enterprise Server for non-mainframe programs under WebSphere MQ.
  • Resource Classes for WebSphere MQ
  • WebSphere MQ-Specific Environment Variables
Parent topic: Enterprise Server configuration and administration
Related concepts
WebSphere MQ Switch Module


CICS and WebSphere MQ

To configure CICS to use WebSphere MQ without triggering, you simply need to define an XA resource switch module.

To configure CICS to use WebSphere MQ with triggering enabled requires that you define both an XA resource switch module and a WebSphere MQ listener.

An older method of defining a trigger, whereby you update the WebSphere MQ fields in the system initialization table (SIT), is still supported, but is now deprecated.

Micro Focus recommends that any new triggers are set up using the special listener provided, ensuring that any triggers set up using the deprecated method are removed, as this could lead to connection conflicts.

Parent topic: Configuring Enterprise Server for IBM WebSphere MQ
Related information
XA Resource Manager Definition for WebSphere MQ
CICS SIT Details
To enable MQ listener support
To create an MQ listener


IMS and WebSphere MQ

IMS programs explicitly connect to, and disconnect from, WebSphere MQ using the MQCONN and MQDISC APIs, and require no configuration.

However, if you wish to use triggering and have WebSphere MQ participate as a resource manager, then you need to define an XA resource switch module and a WebSphere MQ listener.

An older method of triggering using JES and a PSB for the trigger monitor is still supported, but is now deprecated. Micro Focus recommends that you use the new method.

Parent topic: Configuring Enterprise Server for IBM WebSphere MQ
Related concepts
IMS Support Tasks
Related information
XA Resource Manager Definition for WebSphere MQ
To enable MQ listener support
To create an MQ listener
IMS Trigger Monitoring
Configuring Enterprise Server for WebSphere MQ Trigger Monitors


JCL Programs and WebSphere MQ

If your JCL programs do not use DSNRLI, then you must explicitly connect to, and disconnect from, WebSphere MQ using the MQCONN and MQDISC APIs. You need not perform any configuration.

However, if your programs use DSNRLI and you want WebSphere MQ to participate as a resource manager in either a single- or two-phase commit environment, then you need to configure a WebSphere MQ XA resource switch module, which will be associated with the program's unit of work. To establish the correct connection, your program must invoke the DSNRLI functions IDENTIFY, SIGNON, and CREATE THREAD.

Parent topic: Configuring Enterprise Server for IBM WebSphere MQ
Related information
-Specific Environment Variables


Non-Mainframe Programs and WebSphere MQ

If your Enterprise JavaBeans (EJBs) or web services programs are application-managed, then you must explicitly connect to, and disconnect from, WebSphere MQ using the MQCONN and MQDISC APIs. You need not perform any configuration.

However, if your EJBs or web services programs are container-managed, then you need to configure a WebSphere MQ XA resource switch module.

Parent topic: Configuring Enterprise Server for IBM WebSphere MQ
Related information
XA Resource Manager Definition for WebSphere MQ


Resource Classes for WebSphere MQ

The table below defines the name and meaning of each default resource class used in Enterprise Server WebSphere MQ security.

WebSphere MQ Class Name | WebSphere MQ relation
MQADMIN Used mainly for holding profiles for administration-type functions. For example:
  • Profiles for WebSphere MQ security switches
  • Profiles for alternate user security
  • The context security profile
MQCONN | Profiles used for connection security.
MQQUEUE | Profiles used for queue security.
MQPROC | Profiles used in process resource security
  • WebSphere MQ Switch Profiles
  • Switches and Classes
  • How Switches Work
  • Profiles to Control Subsystem Security
  • Profiles to Control Queue Manager Level Security
  • Valid Combinations of Switches
  • Resource Level Checks
  • Profiles for Connection Security
  • Connection Security Profiles for the Batch/TSO adapter
  • Connection Security Profiles for the CICS Adapter
  • Connection Security Profiles for the IMS Adapter
  • Profiles for Queue Security
  • Process Profiles
  • Profiles for Alternate User Security
  • Profiles for Context Security
Parent topic: Configuring Enterprise Server for IBM WebSphere MQ
Parent topic: Resource Classes used by Enterprise Server


Monitoring Enterprise Server

  • Server Instance Statuses
  • Monitoring the Directory Server
  • Collecting and Viewing Data on Transactions
  • Windows Event Log
  • Performance Counters
  • Management Packs for System Center Operations Manager
Parent topic: Enterprise Server configuration and administration


Server Instance Statuses

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

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

In order to access the Enterprise Server Administration user interface, the Directory Server must be running.

When Enterprise Server is installed, the Directory Server is configured to start automatically as a Windows service. As with other Windows services, you can stop the Directory Server and start it again if required.

You can also start Directory Server from the command line using the mfds command. This method of starting the Directory Server is useful if you want to debug applications running as services. Before you can use the mfds command, you must stop Directory Server running as a Windows service. If you start Directory Server using the mfds command, you must stop it using a menu option on the Web interface.

The mfds command also provides options to deinstall and reinstall the Directory Server as a Windows service.

To access the Directory Server using the Web interface, you start a Web browser and enter the address where the Directory Server is running.

Alternatively, if you are running Enterprise Developer,.

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
  • To Start the Directory Server from the Command Line
  • To Stop the Directory Server
  • To stop the Directory Server when not running as a service
  • 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

  1. Open the Windows Control Panel.
  2. Select Services; how you do this differs between Windows operating systems.
  3. In the list of services select Micro Focus Directory Server.
  4. Click Start.
Note: You would normally need to do this only if you stopped the Directory Server using the Services dialog. This is because the Directory Server is configured at installation time to start automatically when Windows starts.
Parent topic: Starting and Stopping the Directory Server
Parent topic: Start and Stop the Directory Server


To Start the Directory Server from the Command Line

  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, stopping the server, and for the installation or removal of Windows services.
    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
Parent topic: Starting and Stopping the Directory Server
Parent topic: Start and Stop the Directory Server


To Stop the Directory Server

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.

  1. Open the Windows Control Panel.
  2. Select Services; how you do this differs between Windows operating systems.
  3. In the list of services select Micro Focus Directory Server.
  4. Click Stop.

From the command line

Enter:
mfds -s
Parent topic: Starting and Stopping the Directory Server
Parent topic: Start and Stop the Directory Server


To stop the Directory Server when not running as a service

When the Directory Server is not running as a Windows service, you can shut it down from the Enterprise Server Administration user interface:

  1. Click Shut down on the menu on the left-hand side of any Enterprise Server Administration Web page.
  2. Click Yes on the confirmation page.
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.
Parent topic: Starting and Stopping the Directory Server
Parent topic: Start and Stop the Directory Server


To Delete the Repository

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

  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 C:\Users\All Users\Micro Focus\Enterprise Developer\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

  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 C:\Users\All Users\Micro Focus\Enterprise Developer\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 C:\Users\All Users\Micro Focus\Enterprise Developer\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

  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 C:\Users\All Users\Micro Focus\Enterprise Developer\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

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

  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
Parent topic: Submitting to a Remote Machine


Monitoring Facilities

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

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 Enterprise Server Security.
Parent topic: Monitoring Facilities
Related information
Introduction to Enterprise Server Security


Viewing a MF Directory Server's Statistics

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

  • 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

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

  • 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

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

  • 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

  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 C:\ProgramData\All Users\Application Data\Micro Focus\<product name> (assuming your %SYSTEMDRIVE% is c:). If the file already exists it will be overwritten.
Parent topic: Viewing the Journal
Parent topic: Monitor Directory Server


To Delete Journal Entries

  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

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:

  • CICS transactions
  • IMS transactions
  • Batch jobs (JCL) - for each JCL job, HSF generates a start record, an end record and one record for each step
  • 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

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.
    Create JCL file records
    This switches on the generation of JCL file (JCLF) records for 'mainframe' files - i.e. those that are accessed with FCDCAT and ASSIGN(EXTERNAL). JCLF records are local to a step, so that multiple records can be generated for a single dataset name in the same job - one record is created for each step in which the dataset is accessed.

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.
    Create JCL File records
    This switches on the generation of JCLF records - collection can be switched on (and off) dynamically.
  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

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 CICS and IMS tasks, the transaction ID
  • for JCL, the job name
  • for Web services, the service name
Program
  • for CICS and IMS tasks, the program name
  • for JCL, the program name or the job number, depending on the JCL record type
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.
User/CC
  • For CICS tasks, the ID of the user that initiated the task.
  • For JCL STEP and END records, the condition code or an error string.
LU/Step
  • For CICS tasks, the logical unit or net name (the identifier of the terminal used to initiate the task).
  • For JCL, either the step name, the JOBSTART(CLASS:jobclass) indicator, or the JOBEND indicator. JOBSTART(CLASS:jobclass) records are generated when a job starts. Job step records displaying the step name - e.g STEP01 - are generated when a step ends. JOBEND records are generated when a job completes.
Parent topic: Collecting and Viewing Data on Transactions
Related information
To start an enterprise server instance


Viewing HSF Information as a .csv File

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:
  • CICS - for CICS transactions
  • IMS - for IMS transactions
  • JCL - JCL job start, step completion and job end events
  • JCLF - for mainframe file events
  • 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 CICS and IMS tasks, the transaction ID.
  • For JCL and JCLF, the job name.
  • For Web services, the service name.
User/DDName/CC
  • For all records except JCL and JCLF, the ID of the user that initiated the task.
  • For JCL STEP and JCL JOBEND records, the related condition code.
  • For JCL JOBSTART records, the user that submitted the job.
  • For JCLF records, the DDName of a file associated with the job step.
LU/Step
  • For CICS tasks, the logical unit or net name (the identifier of the terminal used to initiate the task).
  • For JCL JOBSTART records, the JOBSTART(CLASS=jobclass) indicator.
  • For JCL STEP records, the step name.
  • For JCL JOBEND records, the JOBEND indicator.
  • For JCLF, the step name.
Prog/DSName
  • For CICS and IMS tasks, the program name.
  • For JCL JOBSTART and JOBEND records, the job number.
  • For JCL STEP records, the program name.
  • For JCLF records, the name of the dataset.
Latent/ReadCount
  • The time, in hundredths of a second, between Enterprise Server receiving the request and the task beginning to run. This applies to all records except JCLF records.
  • For JCLF records, the number of reads performed against the file during the related step.
Resp/WriteCount
  • The time, in hundredths of a second, that the task ran for (not including latency time). This applies to all records except JCLF records.
  • For JCLF records, the number of write operations performed against the file during the related step.
API/RewriteCount
  • The time, in hundredths of a second, spent in CICS API (EXEC CICS statements) for this task. This applies to all records except JCLF records.
  • For JCLF records, the number of rewrites performed against the file during the related step.
SQL/DeleteCount
  • The time spent, in hundredths of a second, in SQL API (EXEC SQL statements) for this task. This applies to all records except JCLF records.
  • For JCLF records, the number of record deletes performed against the file during the related step.
IMS/DSDeleteCount
  • The time spent, in hundredths of a second, in IMS DL/I API for this task. This applies to all records except JCLF records.
  • For JCLF records, the number of times the related dataset was deleted during the current step.
DSType
This field is blank for all records except for JCLF records, in which case it is one of:
  • Permanent
  • PC
  • Terminal
  • Sysout
  • Dummy
  • Temp
DSAccessType
This field is blank for all records except for JCLF records, in which case it is one of:
  • Alloc
  • Read
  • Update
  • Delete

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.
TD(x)
For CICS records, the name of a transient data queue (TDQ), blank for non-CICS records.
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

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 Enterprise Developer command prompt, launch casfhsf.exe.

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:
  • CICS= a CICS transaction
  • IMS = an IMS transaction
  • JCL = a JCL batch job
  • WEB = a Web Service
Note: JCLF records do not participate in aggregation processing.
id
The identifier of the transaction, job, service or program ID to be aggregated. If id is "Auto", this is an alias for CICS Auto install transaction (x'feffffff').

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
casfhsf /a /s /ipc:\es\region2\system CICS,ABCD,CICS,WXYZ
This processes cashsf-a.csv in the directory c:\es\region2\system, and aggregates times (in seconds) separately for the CICS transactions ABCD and WXYZ.
Example
casfhsf /op"c:\Users\All Users\Micro Focus"
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 c:\Users\All Users\Micro Focus.

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.
API,min,max | The average time, in hundredths of a second, spent in CICS API (EXEC CICS statements) for this task, and the minimum and maximum times.
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.
IMS,min,max | The average time, in hundredths of a second, spent in IMS DL/I API 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.

Example

  1. An input file cashsf-a.csv was created during a short run of a CICS region.
  2. The following command was executed in the directory containing the input file:
    casfhsf /a /m CICS,ACCT

    This command processes cashsf-a.csv in the current directory, places the output file in the current directory, and aggregates times by the minute.

  3. An output file, OutFile.csv is created. The figure below shows the content viewed in Microsoft Excel:

    This shows, for example, that at 13:45 aggregated statistics for the CICS transaction ACCT are:
    • the number of transactions per second is 0.08
    • the average latency is 10 milliseconds
    • the average response time is 10 milliseconds
    • the total (system) response time is 20 milliseconds
Parent topic: Collecting and Viewing Data on Transactions


Windows Event Log

The Enterprise Server product can be configured to log the console log messages to the Windows Event Log. Each enterprise server instance, which is configured to enable this feature, will then log each console log message as a separate Windows event under the Enterprise Server Windows Event Log. The events logged under the Enterprise Server Windows Event Log can be viewed using the Windows Event Viewer.

  • To Enable Windows Event Logging
  • To Use Windows Event Logging
Parent topic: Monitoring Enterprise Server


To Enable Windows Event Logging

  1. In Enterprise Server Administration, click Edit against the server that you want to configure for Windows Event Logging.
  2. Go to the Windows Monitoring and Management option by selecting the Server, Properties and General tabs.
  3. Choose the category of messages to be logged by selecting the appropriate checkboxes.
  4. Click Apply.
  5. Click OK.
  6. Start the server. If any of the checkboxes were selected, the following message will be displayed upon the console daemon, indicating that Event Logging has been enabled:
    CASCD4005I Windows Event logging Enabled
Parent topic: Windows Event Log
Parent topic: Monitor and Manage Enterprise Server


To Use Windows Event Logging

  1. Start the Windows Event Viewer from Windows Administrative tools, or by typing eventvwr.exe at the Windows command prompt.
  2. To view the event properties logged by the enterprise servers, select the Micro Focus Server Windows Event Log in the Left Hand pane.
  3. To monitor the log from a remote computer, select connect to another computer under the Actions menu.
Note: Severe messages appear in the Event Log as Error Type. These can be distinguished by an ‘S’ at the end of the error code given in the event description.
Parent topic: Windows Event Log
Parent topic: Monitor and Manage Enterprise Server


Performance Counters

You are able to configure Enterprise Server to provide custom Windows performance counters through the WMI infrastructure. Each enterprise server instance that is configured to provide performance counters exposes performance information through the WMI. This information can then be monitored using applications such as the Windows Perfmon tool.

The provided performance counters are:

  • Available Shared Memory
  • Average Request Latency
  • Average Task Duration
  • Dump Count (since start-up)
  • Pending request Count
  • SEP Count
  • Task Count (last 60 seconds)
  • Task Count (since start-up)
  • To Enable Performance Counters
  • To Use Performance Counters
Parent topic: Monitoring Enterprise Server


To Enable Performance Counters

  1. In Enterprise Server Administration, click Edit against the server that you want to configure for Performance Monitoring.
  2. Go to the Windows Monitoring and Management option by selecting the Server, Properties and General tabs.
  3. Select the Allow Performance Monitoring checkbox.
  4. Click Apply.
  5. Click OK.
  6. Start the server. The following message will be displayed in the console daemon to indicate that Performance Monitoring has been enabled:
    CASAM3016I ES Monitoring and Management Support Enabled
Parent topic: Performance Counters
Parent topic: Monitor and Manage Enterprise Server


To Use Performance Counters

  1. Launch the Windows Event Viewer from Windows Administrative tools, or by typing Perfmon.exe at the Windows command prompt.
  2. Right click on the graph in the right hand pane and select Add Counters.
  3. Select Micro Focus Server System from the list in the Add Counters dialog box.
  4. Select the counters to be plotted from the counters list.
  5. Select the servers for which you wish to plot the counters from the instances list.
  6. Click Add.
Note: After starting an enterprise server, it takes up to a minute before Enterprise Server updates the performance information. During this time, all performance counters will have a value of "Zero". Thereon, information is updated every minute.
Parent topic: Performance Counters
Parent topic: Monitor and Manage Enterprise Server


Management Packs for System Center Operations Manager

System Center Operations Manager (SCOM) is a Microsoft product that manages Windows Server Systems. It enables event, health and performance monitoring and also provides the capability to highlight relevant and important information to help prevent issues from going unseen.

Management Packs are provided in Enterprise Server to define specific rules and monitors. In addition, they provide a means of discovering instances of enterprise server instances and their properties, monitoring of the Windows Event Log for key messages and displaying performance counter data.

Integration with Operations Manager requires a SCOM agent to be deployed to each machine that is to be managed. This agent monitors events and performance data based upon rules defined in the Management Packs. For information on how to deploy SCOM agents, refer to the System Center Operations Manager documentation.

There are three Enterprise Server Management Packs:

  • MicroFocus.Server.Core.Library.mp
  • MicroFocus.Server.EnterpriseServer.ManagementPack.mp
  • MicroFocus.Server.EnterpriseServer.MTO.ManagementPack.mp
Note: Discovery occurs for each enterprise server instance regardless of whether it is enabled for event logging or performance monitoring.

The discovery interval is 60 minutes, so a change of properties in a server may not immediately appear in Operations Manager.

  • Monitors
  • Rules
  • Discovery
  • Enterprise Server Tasks
  • To import Server Management Packs into Operations Manager
  • To View Server Instances and Properties in Operations Manager
  • Extending and Overriding Management Packs
Parent topic: Monitoring Enterprise Server


Monitors

A monitor is a state machine that is used to represent a particular aspect of the application, device, or service being monitored. They are used to determine the health state of a particular component and are integral part of the health model. The monitor can check for a single event or a wide range of events that represent many different problems.

When a key message is reported to the event log, it will be indicated in the Health Explorer for the relevant enterprise server instance. The server's overall state will also indicate that an error or warning has occurred.

In the event of an error, a monitor will need to be reset in order to return it to a healthy state. An exception to this is the Shared memory storage constrained message. If a message is detected that indicates the constraint has ended, then the health state for that monitor will return to healthy.

The following monitors, with associated error codes and descriptions, are included in the Micro Focus Management Packs:

  • Monitor Category: Availability
  • Monitor Category: Configuration
  • Monitor Category: Micro Focus Server Operation
  • Monitor Category: Performance
Parent topic: Management Packs for System Center Operations Manager


Monitor Category: Availability

The following Availability monitors, with associated codes and descriptions, are included in the Micro Focus Management Packs:

Database Connectivity
Code | Error Description
CASRM0002S | ODBC resource manager initialization terminated abnormally
Processes
Code | Error Description
CASSP0003E | Process termination recovery initiation failed
CASSP0004E | Process termination recovery initiation failed
CASSP0014S | Process termination due to RTS error
Resources
Code | Error Description
CASSI0006S | Error opening RDO file
CASFC0008I | Error accessing file. File closed and disabled.
CASCS5011W | Failed to open port for TCPIPSERVICE
SEPs
Code | Error Description
CASCD0144S | SEP failed to initialize
CASCD0154S | SEP abended
Server Manager Operation state
Code | Error Description
CASCD0152S | Service execution process manager abended
CASCD0142S | Service execution process manager abended
CASCD0141S | Service execution process manager failed in initialization
CASSI1001S | Service execution process manager initialization failure
CASSI1002S | Server manager failed the license check
CASSI1003W | Service execution process manager initialization error, no MSS license found
CASCD0143S | Service execution process manager failed in termination
CASCD0151S | Service execution process manager abended in initialization
CASCD0153S | Service execution process manager abended in termination
XA Resources
Code | Error Description
CASXO0001S | XA Resource Manager initialization error
CASXO0016S | XA interface initialization failure
CASXO0023S | Severe error detected in XA interface, RM interface disabled
CASXO0025I | XA Switch enabled on demand
CASXO0015I | XA interface initialized successfully
ES Communications Server
Code | Error Description
CASCD0169S | ES Communications Service execution process abended
CASCD1040S | ES Communications Service execution process exited
Parent topic: Monitors


Monitor Category: Configuration

The following Configuration monitors, with associated error codes and descriptions, are included in the Micro Focus Management Packs:

General
Error Code | Error Description
CASSI0005S | Requested SIT could not be found
Parent topic: Monitors


Monitor Category: Micro Focus Server Operation

The following Micro Focus Server Operation monitors, with associated error codes and descriptions, are included in the Micro Focus Management Packs:

Database Connectivity
Error Code | Error Description
CASRM0005S | ODBC resource manager error
Processes
Error Code | Error Description
CASKC6001S | Unable to kill process
Resources
Error Code | Error Description
CASSP0010S | Syncpoint failure - resource state unpredictable
CASSP0011S | Syncpoint failure - resources ROLLEDBACK
CASSP0013S | Rollback failure - resource state unpredictable
XA Resources
Error Code | Error Description
CASXO0002S | Switch Load Module failed to load
Parent topic: Monitors


Monitor Category: Performance

The following performance monitors, with associated error codes and descriptions, are included in the Micro Focus Management Packs:

Shared Memory
Error Code | Error Description
CASKC0007W | Shared memory storage constrained
CASKC0008I | Shared memory storage constraint ended
Transactions (CICS)
Transaction ABENDs
Error Code | Error Description
CASKC0001E | Transaction abend (system)
CASKC0041E | Transaction abend (timeout)
CASKC0042I | Transaction abend (user)
Transaction Thresholds
Error Code | Error Description
CASKC6003I | Transaction threshold breached
CASKC6004I | Transaction completed, but threshold breached
JES Time Threshold (JES only)
Error Code | Error Description
CASKC6002I | Job terminated due to exceeding TIME parameter
IMS Time Threshold (IMS only)
Error Code | Error Description
CASIP0026I | Transaction completed but exceeded its threshold
CASKC6005I | Transaction has exceeded its threshold
Parent topic: Monitors


Rules

Rules collect data from Micro Focus provided Performance Counters and event log occurrences. Alerts can be generated from the collected monitoring data.

An example rule is included which monitors for abnormal SEP termination (CASCD0154S). If this particular error is reported to the event log, then an alert will be raised indicating which enterprise server reported the alert.

Parent topic: Management Packs for System Center Operations Manager


Discovery

Once an agent has been installed on a machine, it will discover all enterprise server instances that reside there. For each instance, the following, if defined, is also discovered:

  • Properties from the General tab in the Enterprise Server Administration pages
  • Listeners and their properties
  • Services and their properties
  • Request Handlers and their properties
  • Packages and their properties
  • CICS properties
  • JES properties
  • JES Initiators and their properties
  • JES printers and their properties
  • IMS properties
  • IMS DB properties
  • IMS TM properties
  • IMS MPRs' and their properties
Note: Discovery will occur for each enterprise server instance regardless of whether it is enabled for event logging or performance monitoring.

The discovery interval is 1 hour, so a change of properties in a server may not immediately appear in Operations Manager.

Parent topic: Management Packs for System Center Operations Manager


Enterprise Server Tasks

The management packs give you two tasks in Operations Manager's Actions pane that you can use to start administration pages.

View Enterprise Server Administration Page
Opens the Enterprise Server Administration page for the machine on which the selected server is installed.
SEPs View
Opens the Enterprise Server Monitor and Control page for the selected server in SEPs view.
Parent topic: Management Packs for System Center Operations Manager


To import Server Management Packs into Operations Manager

Monitoring using the Management Pack definitions begins as soon as an agent has been installed on a client machine.

  1. Start Operations Manager.
  2. In the Operations Console, click Administration.
  3. Right click on Management Packs.
  4. Select Import Management Packs.
  5. Navigate to the directory containing the Enterprise Server Management Packs: %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\cas. Select all and click Open.
  6. Click Import.
Parent topic: Management Packs for System Center Operations Manager
Parent topic: Monitor and Manage Enterprise Server


To View Server Instances and Properties in Operations Manager

  1. Start Operations Manager.
  2. In the Operations Console, click Monitoring.
  3. Navigate the directory tree: Micro Focus Monitoring and Management > Product Name > Enterprise Server . The following are displayed in the tree:
    • Server overall state
    • MSS
    • Performance view

To work with Server overall state take the following steps:

  1. Select Server overall state from the directory tree. A list of enterprise server instances is displayed in the main panel.
  2. To display a list monitoring and performance options for a specific server, right click the server name and take the Open option.
  3. Select the list item you wish to view. To view properties of a specific server, select Diagram view, expand the diagram tree if necessary, and click on the appropriate server icon. To view the health state of a server, select Health Explorer for Server-name.
  4. Select File->Close to return to the list of servers.

To work with MSS take the following steps:

  1. Expand MSS in the directory tree.
  2. Select MSS systems state from the directory tree. A list of MTO enabled enterprise server instances is displayed in the main panel.
  3. To display a list monitoring and performance options for a specific server, right click the server name and take the Open option.
  4. Select the list item you wish to view. To view properties of a specific server, select Diagram view, expand the diagram tree if necessary, and click on the appropriate server icon. To view the health state of a server, select Health Explorer for Server-name.
  5. Select File->Close to return to the list of servers.

To work with Performance view take the following steps:

  1. Select Performance view from the directory tree. A graph with a list of counter instances for each enterprise server running that is enabled for performance monitoring is displayed in the main panel.
  2. Select the appropriate performance counter check box to plot the counter value on the graph.
Parent topic: Management Packs for System Center Operations Manager
Parent topic: Monitor and Manage Enterprise Server


Extending and Overriding Management Packs

Although the Enterprise Server Management Packs cannot be modified directly, custom Management Packs can be created to override and extend their behaviour. Refer to the System Center Operations Manager documentation for details on how to do this.

Parent topic: Management Packs for System Center Operations Manager


User Exits for Request Handlers

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

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

To help COBOL and C programmers, we provide a COBOL copybook (cbltypes.cpy) and a C header file (svext.h) with Enterprise 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

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

To deploy a user exit program, copy it into %ProgramFiles(x86)%\Micro Focus\Enterprise Server\bin or \bin64 (64-bit).

Parent topic: User Exits for Request Handlers


Troubleshooting

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
Parent topic: Enterprise Server configuration and administration


Determining the Failure Type

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

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

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

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

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.

  • One Type Of Request is Failing
  • All client requests are failing
Parent topic: Unexpected System Termination


One Type Of Request is Failing

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

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

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 C:\Users\All Users\Micro Focus\Enterprise Developer\mfds:

  • usr.dat

  • ugp.dat

  • ace.dat

  • prm.dat

These files are initially created from the cciusers.dat file located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin. 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

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

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

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

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin and \bin64 . 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

files=number-of-files
Specifies the number of log files.
Parent topic: Communications Process Log Files


filesize

filesize=maxsize
Specifies the maximum size of a log file in kilobytes (KB)
Parent topic: Communications Process Log Files


dscontrol

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

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

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

  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

Each Enterprise Server writes log, dump and trace information to files in its System Directory.

The default location for the System Directory is usually a sub-folder under %USERPROFILE%\Documents\Micro Focus\<product name>\WORKAREA<region name> where:

  • %USERPROFILE% has a different value depending on whether you start the region from MFDS or a command prompt:
    • When started from MFDS, uses the user profile of the account associated with the service. If this is the local system account, the %userprofile% will be that of the local system account.
    • When started from the command line, uses the environment variable %USERPROFILE%
  • <product name> is the name of the product you installed
  • <region name> is a product component

You can change the location of the System Directory by editing the Enterprise Server's definition in Enterprise Server Administration.

If you are running the Directory Server as a service that logs on as the Local System account (LocalService), any Enterprise Server that it starts will also run under that account. Hence, the default location of the log file could be <local system account profile>\My Documents\Micro Focus\<product name>\ X.X\WORKAREA\es-name\console.log. By default, Windows hides the LocalService subdirectory of Documents and Settings. In order to view this directory, you must configure your Windows Explorer so that: Show hidden files and folders is set, and Hide protected operating system files is not set.

  • To Change the System Directory
Parent topic: Collecting Information
Related information
Moving the Diagnostics Data


To Change the System Directory

  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 System Directory location.
    Note:
    • If you specify a directory in this field, that directory must exist; Enterprise Server does not create it for you.
    • The System Directory cannot be shared between enterprise servers.
  3. Click OK.
  4. You must restart the server for the changes to take effect.
    1. If the server is started, stop it.
    2. Start the server.
Parent topic: Enterprise Server System Directory
Parent topic: Work with Servers


Dumps and Traces

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

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

The minimum items for data capture are:

  • Your enterprise server's System Directory, %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\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).
    Note: If your enterprise server is running under the Windows LocalService account, the directory might be hidden by Windows. See System Directory for more information.
  • A copy of the file edver, located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc , 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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin and \bin64 .
  • The Directory Server configuration directory, usually under the C:\Users\All Users\Micro Focus\Enterprise Developer\mfds directory.
  • The Directory Server log file (usually under the %ProgramData%\Micro Focus\Enterprise Developer 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 from the Windows Task Manager
  • A list of shared memory areas and semaphores. You can obtain this using third-party tools such as Process Explorer
  • A list of network connections and listening sockets, obtained by running the netstat command.
  • Optionally, a list of open files. You can obtain this using third-party tools such as Process Explorer
Note:
  • The operating system tools that you can use to obtain information such as Process Explorer 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

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

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

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

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 and %SystemDrive% is C:

In the examples below, Enterprise Server is installed as part of Enterprise Developer:

copy *.rec "%USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\diagnostics-server-name"
copy console.log "%USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\diagnostics-server-name\console.aux"
copy console.bak "%USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\diagnostics-server-name\console.bak"

Here is a sample script that copies the required data to a diagnostics server called diagnose.

copy *.rec "%USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\diagnose\"
copy console.log "%USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\diagnose\console.aux"
copy console.bak "%USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\diagnose\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

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

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

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

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 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
  • To Configure Run-time Core Dumps
Parent topic: Troubleshooting


To Change the Trace Dataset

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

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

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

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 Transfer the In-memory Trace Data to the Auxiliary Dataset at Rollover

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: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC


To View 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 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

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 client process

  1. Click Clients in the menu.
  2. Click Trace next to the client process for which you want to view a local trace.

    The trace is formatted and displayed. To return to ESMAC, click Back in your browser.

Note: Local traces are available only for WebSphere MQ listeners and communications processes (MFCS).
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

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

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

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=131
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


Enterprise Server Administration Console Help Pages

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

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

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.

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

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

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

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

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

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

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. MSS in parentheses after MFES indicates that the server has Mainframe Subsystem Support (MSS) enabled.

  • 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

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 %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\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.

Mainframe Subsystem Support

Check this to indicate that this server is an MSS-enabled server, that is, a server that can run CICS applications.

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.

Application

Check this to indicate that the server is to trace the CICS API calls made by a CICS application.

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

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

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: MSS Support
  • Server Instance Properties: MQ Support
  • 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

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 %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\es-name%USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA/es-name, where es-name is the name of the enterprise server.

Note: On Windows, the procedure for starting an enterprise server instance is implemented by Micro Focus Directory Services (MFDS). By default, the MFDS process runs as a Windows service using the local system account, whereby the environment variable %USERPROFILE% resolves to C:\Windows\system32\config\systemprofile. As MFDS is a 32-bit application, when starting an enterprise server instance from a browser, Windows maps this location to C:\windows\syswow64\config\systemprofile. However, when starting an enterprise server instance from the command line, the MFDS process uses the logged-on user's account, which means that the environment variable %USERPROFILE% maps to C:\Users\<userid>. To avoid the confusion of the work files being located in two directories, specify a system directory.

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).

Windows Monitoring and Management

Use these fields to specify and configure the performance and event logging options 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.

Allow Performance Monitoring

Check this box if you want to enable a server to provide performance counters through the Windows Management Instrumentation. Performance information can then subsequently be viewed through Windows Perfmon.

Event Logging

Check the appropriate boxes to specify which events will be logged to the Windows Event Log.

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

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, .so on 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

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 an XA resource manager (XAR) ID, used internally to identify a particular XA configuration, and must be unique within the enterprise server region. This ID is used by JES-initiated jobs. See Executing TSO Commands in Batch Mode (IDAEFT01), and Planning and Designing XARs for more information. Mandatory.
Name
Specify the name by which the XAR 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 RM switch module executable file (.dll) that contains the entry point that returns the xa_switch_t structure to the enterprise server. We strongly recommend that you include the full path to the executable file. 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 often the user ID and password credentials for connecting to the database. The contents of this string are database-specific.

Where the RM switch module 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 XAR 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 XAR definition.
Enabled
Check this to enable the XAR. It is checked by default.
Parent topic: Server Instance Properties: XA Resources


Server Instance Properties: MSS Support

Check Mainframe Subsystem Support enabled to .

Use this page to enable MSS for this enterprise server instance.

To access this page:

  1. On the server instance screen, select the Server > Properties > MSS tabs.
Note:

You can use the resolved value of an environment variable in any fields for the entry of file or directory paths. To do this, prefix the environment variable you want to include with a dollar ($) sign; for example:

$production\programs

where production is an environment variable.

If you want to use a dollar sign as part of the value, rather than as an indicator of an environment variable, you must escape the dollar sign character with a backslash(\); for example:

\$production\programs

In this case, $production will not be replaced by the value of the environment variable.

  • Server Instance Properties: MSS CICS
  • Server Instance Properties: MSS JES
  • Server Instance Properties: MSS IMS General
  • Server Instance Properties MSS IMS DB General
  • Server Instance Properties MSS IMS DB Compression
  • Server Instance Properties: MSS IMS DB Locking
  • Server Instance Properties MSS IMS DB Recovery
  • Server Instance Properties: MSS IMS TM General
  • Server Instance Properties: MSS IMS TM MPRs
Parent topic: Edit Server Instance Properties


Server Instance Properties: MSS CICS

Use this page to enable Mainframe Subsystem Support (MSS) and configure CICS support 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 > Properties > MSS > CICS tabs.
CICS enabled

Indicates whether or not CICS is enabled. In this release, CICS is automatically enabled when Mainframe Subsystem Support is enabled.

System Initialization Table

Specify the system initialization table (SIT) to be used by this enterprise server. Defaults to DFH$IVP.

Transaction Path

Specify the full path of the CICS transaction programs that will run in this enterprise server. Separate multiple paths with semi-colons on Windows or colons on UNIX. Mandatory if you use any other SIT than DFH$IVP.

VSAM File Path

Specify the full path of the VSAM files required by the CICS transaction programs that will run in this enterprise server. Separate multiple paths with semi-colons on Windows or colons on UNIX. Mandatory if you use any other SIT than DFH$IVP.

Map Path

Specify the full path of any BMS map load modules required by the CICS transaction programs that will run in this enterprise server. Separate multiple paths with semi-colons on Windows or colons on UNIX. Mandatory if you use any other SIT than DFH$IVP.

Resource Definition File Path

Specify the full path of the resource definition file for this enterprise server. Mandatory if you use any other SIT than DFH$IVP.

EZASOKET support

Check this to enable support for CICS and JCL applications that use the EZASOKET APIs.

Parent topic: Server Instance Properties: MSS Support


Server Instance Properties: MSS JES

Use this page to enable Mainframe Subsystem Support (MSS) and to configure the Job Entry Subsystem (JES) for JCL on 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 > Properties > MSS > JES tabs.
Job Entry Subsystem enabled

Check this to enable the Job Entry Subsystem for this server.

JES Path

Specify the path for the executable files that your JCL jobs will run.

Put your .gnt and .dll files on this path. For debugging, you will also need to put your .int, .idy and .cbl files on this path.

System Catalog

Specify the full name (including the path) of your system catalog file. This file holds the details of data files, their attributes and locations.

Note: You cannot share a catalog between servers.
Default Allocated Dataset Location

Specify the default directory to be used for the creation of new data sets.

System Procedure Library

Specify the name of your system procedure library.

Fileshare Configuration Location

Specify the path and name of the Fileshare Configuration file.

Parent topic: Server Instance Properties: MSS Support


Server Instance Properties: MSS IMS General

Use this page to enable Mainframe Subsystem Support (MSS) and configure IMS support for this enterprise 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 > Properties > MSS > IMS > General tabs.
IMS enabled

Indicates whether or not IMS is enabled for this enterprise server.

Codeset bias

Choose the default codeset to use for transactions running on this enterprise server:

  • ASCII - Transactions use ASCII.
  • EBCDIC - Transactions use EBCDIC.
Configuration directory

This path maps to the ES_IMSCFG environment variable, and is reserved for future use.

ACB file directory

Specify the location of the .dat, .idx, and .acb files produced by DBDGENs, IMSGENs and PSBGENs. This field maps to the ES_ACBLIB environment variable.

GEN file directory

Specify the full path to the transaction definition file for this enterprise server. This field maps to the ES_IMSLIB environment variable.

Parent topic: Server Instance Properties: MSS Support


Server Instance Properties MSS IMS DB General

Use this page to set the IMS database path.

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 > MSS > IMS > DB > General tabs.
Database path

Specify the location of the IMS data files and any .slf files to be used by the IMSDBUEA segment exit routine.

Parent topic: Server Instance Properties: MSS Support


Server Instance Properties MSS IMS DB Compression

Use this page to set IDX-8 KEY/DATA compression options.

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 > MSS > IMS > DB > Compression tabs.
Key compression
Indicates whether or not key compression is turned on.
Data compression

The data compression routine number. Valid values are the same as those that can be specified for the Compiler directives DATACOMPRESS and KEYCOMPRESS.

Parent topic: Server Instance Properties: MSS Support


Server Instance Properties: MSS IMS DB Locking

Use this page to set IMS database locking options.

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 > MSS > IMS > DB > Locking tabs.
Enable IRLM locking

When checked, enables the Internal Lock Resource Manager (IRLM) locking algorithm. IRLM locking more closely parallels mainframe IMS database DB locking behavior, reducing data constraint and potential for deadlock. Maps to the ES_IMS_IRLM environment variable.

Dump on lock timeout

When checked, creates a system dump when IMS DB control is unable to access a locked record before the specified Locked resource timeout period expires. Maps to the ES_IMS_DUMP_ON_TIMEOUT environment variable.

Dump on deadlock
When checked, creates a system dump when a deadlock is detected. Maps to the ES_IMS_DUMP_ON_DEADLOCK environment variable.
Locked resource timeout

The number of seconds during which IMS DB control continues to retry a locked record before timing out. Valid values are 0 to 65535. The default is 30 seconds; a value of 0 indicates an indefinite wait time. Maps to the ES_IMS_LOCK_TIMEOUT environment variable.

Parent topic: Server Instance Properties: MSS Support


Server Instance Properties MSS IMS DB Recovery

Use this page to enable IMS forward recovery and specify a path for forward recovery IMS transaction logs.

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 > MSS > IMS > DB > Recovery tabs.
Enable rollforward recovery

When checked, enables the IMS forward recovery feature. Maps to the ES_IMS_ROLLFORWARD environment variable.

IMS transaction log path

Specify the path to a directory where IMS forward recovery log files are stored. Maps to the ES_IMS_TLOG_PATH environment variable.

Parent topic: Server Instance Properties: MSS Support


Server Instance Properties: MSS IMS TM General

Use this page to configure IMS TM support for this enterprise 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 > Properties > MSS > IMS > TM > General tabs.
Message queue

Use these fields to define the attributes of the IMS message queue.

Use default queue name
Check this to use the default queue path and filename, which by default is %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\esname\IMSMESGQ.dat where esname is the name of your enterprise server region.
Name

Provide an alternative path and filename for the IMS message queue.

Maximum blocks

The message queue consists of blocks of approximately 64K bytes. These blocks consist of 254 segments (not message segments) which are the allocation unit for queue space.

Specify the maximum number of blocks to be used to store the message queue. If necessary, you can dynamically change this number while the enterprise server is running. The value must be in the range of 4 through 63488. The default for an initial server definition is 32.

When space is not available, a TM thread waits until the allocation request can be satisfied. The failure mode for "out of space" is a hang condition.

Note: To decrease the likelihood of a hang condition due to lack of space, Enterprise Server reserves a percentage of the allocated space (a cushion) to enable graceful intervention should it be required. In this case, to facilitate recovery, other message queue operations are restricted. These restrictions are removed when the cushion allocation is reacquired by TM. You can change the cushion percentage dynamically. See IMS Control for details.
Queue buffer count
This is the tuning control. More buffers means less swapping of blocks in memory for message queue activity. The default is 2.
Note: Give careful thought before changing this setting.
Cold start

Choose what information is deleted when you next start this enterprise server:

  • None - No information is deleted. Default.
  • Stats only - Only statistics are deleted.
  • Definitions and stats - Resource definitions and statistics are deleted.
  • Everything - A fresh copy of the message queue dataset is allocated, discarding all previous content.
Persist

Check this to specify that the action you specified in the Cold start option occurs each time this enterprise server starts. Default is unchecked.

MFS path

Specify the location for the files produced by MFSGENs. Default is $IDE_MODPATH.

MFS attribute bias

Choose how attributes are assumed to be defined for transaction programs running on this enterprise server:

  • Binary - Default. The programs define attributes as binary values, for example:
    05 ATTRIBUTE-VARIABLES.
   10 CURSOR-ATTR    PIC X(2) VALUE X"C0C1".
   10 ERROR-ATTR     PIC X(2) VALUE X"C0C9".
   10 OK-ATTR        PIC X(2) VALUE X"00C1".
   10 PROT-ATTR      PIC X(2) VALUE X"00F1".
  • Character - The programs define attributes as characters, for example:
    05 ATTRIBUTE-VARIABLES.
   10 CURSOR-ATTR PIC X(2) VALUE "{A".
   10 ERROR-ATTR PIC X(2) VALUE "{I".
   10 OK-ATTR PIC X(2) VALUE " A".
   10 PROT-ATTR PIC X(2) VALUE " 1".

    This setting only has an effect on programs compiled using the ASCII character set; it is ignored for programs compiled using EBCDIC.

    Where you specify Character, Enterprise Server will automatically translate the values of MFS attributes to those that would be used if the program were compiled as EBCDIC. For example: the hexadecimal 7B41 value produced by assigning '{A' to an attribute and compiling with ASCII, will be converted to the correct C0C1 value. Where you specify that attribute values have been coded as binary data, Enterprise Server will take no action.

MFS null character

Specify the character to use as the MFS NULL character. You can enter the value in character or hexadecimal form. The default is Hexadecimal 0x00.

This setting only has an effect on programs compiled using the ASCII character set; it is ignored for programs compiled using EBCDIC.

Actvity keypoint frequency

Specify how many thread requests are to be processed before a keypoint is generated. This must be in the range 0 through 65535. The default is 64. Specifying 0 indicates that keypoints are only generated when the enterprise server starts and shuts down.

Trailing space

Check this to specify that you must add a trailing space when entering transaction names in this enterprise server. Default is checked.

Transaction threshold

Specify the maximum length of time in seconds that a transaction can run before a message is logged to the console to indicate that it has exceeded its threshold. This must be in the range 0 through 65535. A value of 0 indicates that there is no threshold. Default is 0.

Application path

Specify the location of the transaction programs running on this enterprise server. Default is $IDE_LAODLIB.

Parent topic: Server Instance Properties: MSS Support
Related concepts
Configuring the IMS Message Queue
Dynamic IMS Message Queue Expansion
Dynamic IMS Message Queue Performance Tuning
Related tasks
To enable dynamic IMS message queue performance tuning
To dynamically tune IMS message queue performance
To dynamically adjust the IMS message queue configuration
Related reference
IMS Control


Server Instance Properties: MSS IMS TM MPRs

Use this page to configure message processing regions (MPRs) for this server. From this page you can also:

  • View a list of MPRs
  • Add a new MPR
  • Edit an existing MPR

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 > MSS > IMS > TM > MPRs tabs.
Edit

Click this to edit the MPR definition.

Name

Shows the name of the MPR.

Class

The list of transaction classes that this MPR can run.

Description

Shows an optional text description of the MPR.

Add

Click this to add an MPR.

Note: You can specify a maximum of four classes in the Transaction Class field. You must separate each class by a comma. The classes you specify must be less than 32-bytes long. If you specify more than four classes only the first four are used. When you start the enterprise server instance you see a message (CASIP0013I) in the console.log that shows which classes have been registered for use.
Parent topic: Server Instance Properties: MSS Support


Server Instance Properties: MQ Support

Use this page to enable MQ middleware and listeners for this enterprise server instance. The enterprise server instance must be in Stopped status to save any configuration changes made here.

To access this page:

  1. On the server instance screen, select the Server > Properties > MQ tabs.
  • Server Instance Properties: MQ General
  • Server Instance Properties: WebSphere MQ Listeners
  • Server Instance Properties: Add MQ Listener
  • Server Instance Properties: Edit MQ Listener
Parent topic: Edit Server Instance Properties


Server Instance Properties: MQ General

Use this page to enable MQ listener support.

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 > MQ > General tabs.
MQ listener support enabled

When checked, enables MQ listener support for the MQ IMS bridge feature. Maps to the ES_MQ_LISTENER environment variable.

Parent topic: Server Instance Properties: MQ Support


Server Instance Properties: WebSphere MQ Listeners

Use this page to add new MQ listeners and modify existing MQ listeners.

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 > MQ > MQ Listeners tabs.
Edit
Click this to edit the details for this MQ listener.
Enabled
A check mark indicates that this listener is enabled.
Name
The name of the MQ listener.
Queue
The name of the MQ queue monitored by this listener. This queue must be defined for the specified Queue Manager.
Queue Manager
The name of the queue manager that contains the specified Queue. You create Queue Managers and Queues in WebSphere MQ.
Add

Click this to add a new MQ listener.

Parent topic: Server Instance Properties: MQ Support


Server Instance Properties: Add MQ Listener

Use this page to define the details of a new MQ listener.

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 > MQ > MQ Listeners tabs.
Name
Specify a name for the new MQ listener.
MQ Queue Name
Specify the name of an existing MQ Queue defined for the specified MQ Queue Manager.
MQ Queue Manager Name
Specify the name of an existing MQ Queue Manager. You create Queue Managers and Queues in WebSphere MQ.
Enabled

When checked, enables the new MQ listener.

Parent topic: Server Instance Properties: MQ Support


Server Instance Properties: Edit MQ Listener

Use this page to edit the details of an existing MQ listener.

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 > MQ > MQ Listeners tabs.
Name
Specify a name for the new MQ listener.
MQ Queue Name
Specify the name of an existing MQ Queue defined for the specified MQ Queue Manager.
MQ Queue Manager Name
Specify the name of an existing MQ Queue Manager. You create Queue Managers and Queues in WebSphere MQ.
Enabled

When checked, enables the MQ listener.

Parent topic: Server Instance Properties: MQ Support


Server Instance Properties: Scripts

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

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

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

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

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

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.

Application

Check this to indicate that the server is to trace the CICS API calls made by a CICS application.

Exit

Check this to indicate that the server is to trace user and system exits.

Parent topic: Server Instance Diagnostics


Server Instance Diagnostics: Dump

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

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

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 Communications Server 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.

Unless you have customized your system, there is only one Communications Server console log file (log.html). This file resides in the directory you specified in the System Directory field on the Properties tab for the server. This log file may become quite large, as the system is continually appending data to it.

If you wish to configure your system to have more than one log file, you can enable the rotating log file feature. To do this, you edit the file mf-server.dat, which resides in the product bin directory (Windows), or in the $COBDIR/etc directory (UNIX). You need to add two parameters under [logging]:
files=number | Specifies the number of log files before rotation occurs.
filesize=kilobytes | Specifies the size in kilobytes of each log file.

Example:

[logging]
files=3
filesize=100
Note: Micro Focus suggests that you make a backup copy of mf-server.dat before you modify it.
Parent topic: Server Instance Diagnostics


Server Instance Properties: Security

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)

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.Debug
  • 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. You can also monitor and control CICS-enabled applications, and create and edit CICS SITs, startup lists, groups, resources, and so on. 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.

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.
  • Submit JCL jobs and view and update spool queues and the catalog.
  • 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.
JES
When you select this, you can click:
  • Spool - to view and manage spool queues.
  • Catalog - to view and manage the catalog and data sets.
  • Control - to submit JCL jobs and start batch initiator and batch printer SEPs.
  • Locks - to view the current resource locks for this server.
IMS
When you select this, you can click:
  • Transact - to view the defined IMS transactions
  • Control - to perform IMS-related administration functions
MQ
When you select this, you can click:
  • Input Qs - to view the status of the input queues for defined MQ listeners.
  • Output Qs - to view the status of MQ output queues.
Active
When you select this, you can click:
  • ACEEs - to view the active ACEEs for this server.
  • DCT - to view the active DCTs for this server.
  • FCT - to view the active FCTs for this server.
  • ICE - to view the interval control elements for this server.
  • JCT - to view the active JCTs for this server.
  • Locks - to view the current resource locks for this server.
  • PCT - to view the active PCTs for this server.
  • PPT - to view the active PPTs for this server.
  • SysC - to view the active CCI connection definitions for this server.
  • TST - to view the active TSTs for this server.
  • T-Type - to view the active T-Types for this server.
  • TCPIPSv - to view the active TCPIPSERVICEs for this server.
  • URIMap - to view the active URIMAPs for this server.
  • Pipeline - to view the active PIPELINEs for this server.
  • WebSvc - to view the active WEBSERVICEs for this server.
  • RNL - to view the active RNLs for this server.
by Group
When you select this, you can click:
  • Groups - to view the CICS resource groups for this server.
  • Startup - to view the startup lists for this server.
  • SIT - to view the SITs for this server.
by Start L
Displays the resources, defined for the startup list used by the SIT in use on this server, and the resource groups they are associated with. When you click this, you can select:
  • DCT - to view the DCTs in this startup list.
  • FCT - to view the FCTs in this startup list.
  • JCT - to view the JCTs in this startup list.
  • PCT - to view the PCTs in this startup list.
  • PLT - to view the PLTs in this startup list.
  • PPT - to view the PPTs in this startup list.
  • Sys62 - to view the LU6.2 connection definitions in this startup list.
  • SysC - to view the CCI connection definitions in this startup list..
  • Term - to view the Terminal definitions in this startup list.
  • TST - to view the TSTs in this startup list.
  • T-Type - to view the T-types in this startup list.
  • XAT - to view the XA-compliant database table definitions in this startup list.
  • TCPIPSv - to view the TCPIPSERVICEs in this startup list.
  • URIMap - to view the URIMAPs in this startup list.
  • Pipeline - to view the PIPELINEs in the startup list.
  • WebSvc - to view the WEBSERVICEs in the startup list.
by Type
Displays the resources available on this server, by type, and shows the resource group the resource is associated with. When you click this, you can select:
  • DCT - to view the available DCTs.
  • FCT - to view the available FCTs.
  • JCT - to view the available JCTs.
  • PCT - to view the available PCTs.
  • PLT - to view the available PLTs.
  • PPT - to view the available PPTs.
  • Sys62 - to view the available LU6.2 connection definitions.
  • SysC - to view the available CCI connection definitions.
  • Term - to view the available Terminal definitions.
  • TST - to view the available TSTs.
  • T-Type - to view the available T-Types.
  • XAT - to view the available XA-compliant database table definitions.
  • TCPIPSv - to view the available TCPIPSERVICEs.
  • URIMap - to view the available URIMAPs.
  • Pipeline - to view the available PIPELINEs.
  • WebSvc - to view the available WEBSERVICEs.
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.

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 CICS transaction, 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.
  • Perf Enabled - enables reporting of performance data that can be viewed in Perfmon and Operations Manager,
  • Force Phase In - the current state of Force Phase In. If Force Phase In is set, MSS reloads programs each time they are invoked. This applies only to programs that are not marked resident and have not been loaded with the hold attribute. If Yes, Force Phase In is set; if No, it is not. You can set the state of Force Phase In on the Control page, which can be displayed by clicking Control
  • 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.

Startup

This group is displayed only if you have enabled MSS. It contains the following information:

  • Sit - the name of the SIT currently used by this server.
  • PLT-PI - the program list table (PLT) that specifies the initialization programs to be run when the region is started. If this is blank, no special processing is done when the region is started.
  • SYSID - the system ID of the SIT.
  • PLT-SD - the program list table (PLT) that specifies the shutdown programs to be run when the region is stopped. If this is blank, no special processing is done when the region is stopped.
  • Fileshare user - the user ID used by the region to log on to all Fileshare servers that MSS is configured to use.
  • Security - indicates whether or not the server has security enabled.
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).

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

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

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.

Latency+Resp
The sum of latency and response time averages.
Transaction
The name of task:
  • for CICS and IMS tasks, the transaction ID
  • for JCL, the job name
  • for Web services, the service name
Program
  • for CICS and IMS tasks, the program name
  • for JCL, the program name or the job number, depending on the JCL record type
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.
User/CC
  • For CICS tasks, the ID of the user that initiated the task.
  • For JCL STEP and END records, the condition code or an error string.
LU/Step
  • For CICS tasks, the logical unit or net name (the identifier of the terminal used to initiate the task).
  • For JCL, either the step name, the JOBSTART(CLASS:jobclass) indicator, or the JOBEND indicator. JOBSTART(CLASS:jobclass) records are generated when a job starts. Job step records displaying the step name - e.g STEP01 - are generated when a step ends. JOBEND records are generated when a job completes.
Parent topic: HSF


Control

Use this page to view and change control information for this server.

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.

Force Phase In, Yes

Check this to have MSS reload programs each time they are invoked. This applies only to programs that are not marked resident and have not been loaded with the hold attribute.

Admin
The number of Admin SEPs defined
Initial Tran
The transaction to run when a TN3270 session connects to the server.
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 or TN3270 client 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.

Input

Shows the maximum time in seconds allowed for operator response to an explicit CICS RECEIVE command before 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, or if the program executes the EXEC CICS DUMP command. 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
Sys
Check this to indicate that MSS should produce a dump if an abend occurs in its own code.
Tran
Check this to indicate that MSS should produce a dump if an abend occurs in any of your transaction programs. If you check this field, then you can control whether or not a dump is produced for an individual program by checking or unchecking Dump on abend on the PCT properties dialog box. If you leave this field unchecked, MSS ignores the setting of Dump on abend on the PCT properties dialog box.
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.
Create JCL file records
This switches on the generation of JCL file (JCLF) records for 'mainframe' files - i.e. those that are accessed with FCDCAT and ASSIGN(EXTERNAL). JCLF records are local to a step, so that multiple records can be generated for a single dataset name in the same job - one record is created for each step in which the dataset is accessed.

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
dmp
Check this to indicate that MSS is to trace its dump control component.
lock-data
Check this to trace lock management for non-threaded processes.
scp
Check this to indicate that MSS is to trace its storage control component.
tsc
Check this to trace calls to the castsc process.
exits
Check this to indicate that MSS is to trace the user exits.
msg
Check this to indicate that MSS is to trace its messages component.
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.
reqh
Check this to indicate that MSS is to trace its request handler component.
tmp
Check this to indicate that MSS is to trace its table management component.
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.
rm
Check this to indicate that MSS is to trace its resource manager component.
trd
Check this to trace thread processing in all threaded processes.
xfp
Check this to trace data in transformer processing.
jcp
Check this to indicate that MSS is to trace its journal control component.
rts
Check this to indicate that MSS is to trace its run-time system (application container) component.
trd-enq
Check this to trace processes and data in transformer processing.
xfp-all
Check this to trace data and processes in transformer processing.
tcp
Check this to indicate that MSS is to trace its terminal control component.
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.
JCL/JES
common
Not used.
hsf
Check this to indicate that MSS is to trace the creation of Historical Statistics Facility (HSF) records for JCL.
CICS
api

Check this to indicate that MSS is to trace the CICS API calls.

icp
Check this to indicate that MSS is to trace its interval control component.
ts-td
Check this to indicate that MSS is to trace its temporary storage/transient data (TS/TD) component.
fcp
Check this to indicate that MSS is to trace its file control component.
kcp
Check this to indicate that MSS is to trace its task control component.
user
Check this to enable a user trace.
IMS
api
Check this to indicate that MSS is to trace IMS DL/I API entry points.
dbc
Check this to indicate that MSS is to trace IMS DB control processing.
i/o
Check this to indicate that MSS is to trace IMS physical/virtual file I/O.
sys
Check this to indicate that MSS is to trace miscellaneous IMS processing.
cli
Check this to indicate that MSS is to trace IMS MPR, JES and SEP processing.
ES-DB
Check this to indicate that MSS is to trace ES IMS DB processing.
stg
Check this to indicate that MSS is to trace IMS dynamic memory allocation/freeing.
TM-ctl
Check this to indicate that MSS is to trace IMS TM control processing.
data
Not used.
ES-stg
Check this to indicate that MSS is to trace ES IMS memory management.
DB-thread
Check this to indicate that MSS is to trace lock management for IMS DB.
TM-thread
Check this to indicate that MSS is to trace lock management for IMS TM.
TM-buffer
Check this to indicate that MSS is to trace the buffer for IMS TM lock management.
MQ
mq
Check this to trace
mq-thread
Check this to trace
mq-data
Check this to trace
mq-enq
Check this to trace
mq-data-all
Check this to trace
mq-trd-stg
Check this to trace
Communications
cci
Do not check this unless advised by Micro Focus.
data
Check this to trace basic data in the communication module and IMS TM.
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 and IMS TM.
cg-thread
Check this to trace lock management in the communications module.
Memory Strategy
Use this diagnostic feature to control the frequency and type of runtime memory validation, as well as specifying the processes to which these settings apply. You use this facility to help track down memory violations and corruptions. Unless you are directed otherwise by Support, Micro Focus recommends that you use only the default settings, which result in the most efficient use of memory. Setting these values inappropriately may result in a degradation of system performance and excessive memory usage. Using invasive settings in a development or user acceptance environment may be acceptable and even desirable, but you should apply caution when used in a production environment. You set the desired memory strategy at the time you wish to diagnose a particular problem, and reset the strategy when the diagnosis is complete.
Note: This feature is used for diagnosing "in-flight" memory problems. To diagnose system start-up or PLT program problems, you need to use the environment variable ES_MEM_STRATEGY .
You select the processes within Enterprise Server that you wish to monitor, and are:
SEPs
Service execution processes - recommended for diagnosing most user application memory problems.
Initiators
Job Entry Sub-system (JES) initiators - recommended for diagnosing JCL applications.
MPRs
Message processing regions - recommended for diagnosing IMS applications.
MFCS
Micro Focus Communication System - use this setting when advised to do so by Support.
TMC
Transaction Manager Control - use this setting when advised to do so by Support.
DBC
Data Base Control - use this setting when advised to do so by Support.
TSC
Temporary Storage Control (CASTSC), which includes channels and containers - use this setting when advised to do so by Support. See Enterprise Server Processes for more information.
TRC
Trace Control (CASTRC) - use this setting when advised to do so by Support.
MQB
MQSeries - use this setting when advised to do so by Support.
For each process that you wish to monitor, you can set the following values:
Task Validate Frequency

How often ES validates memory. If you specify 0, no validation occurs. If 1, the check is always at end of task or step, otherwise, after this number has been reached. By using a lower number, with the exception of 0 or 1, you can pinpoint a corruption more easily, the trade-off being slower response times. The number applies to tasks for transactions and to job steps for JCL, and is from a drop-down list of cubed cardinal numbers.

Tip: Using 0 is effectively a toggle to enable/disable a particular processing area. Therefore, you can define a configuration, and switch it in and out as desired.

Default: 0.

Retain Free Count

How many blocks of storage the run-time system (RTS) retains on a free memory request for reuse. This value works together with Check Free. See the topic for the run-time tunable memory strategy for more information.

Default: 100.

Validate on alloc/free

Check this entry to tell the RTS to check all memory blocks for corruption every time memory is allocated or freed. See the topic for the run-time tunable memory strategy for more information.

Validate Container RH

Check this entry to tell the RTS to validate memory prior to, and return from, request handler functions in the COBOL container.

Validate Container Exec

Check this entry to tell the RTS to validate memory prior to, and return from, user application program execution in the COBOL container; such programs include Web Services and IMS.

Reuse Free

Check this entry to tell the RTS to reuse freed blocks to satisfy new memory allocation requests. See the topic for the run-time tunable memory strategy for more information.

Check Free

Check this entry to tell the RTS to monitor for subsequent corruption the last n memory blocks freed, where n is the value specified in Retain Free Count. See the topic for the run-time tunable memory strategy for more information.

Guard Bytes

Check this entry to tell the RTS to prepend and append check bytes to each block of memory being allocated. See the topic for the run-time tunable memory strategy for more information. Micro Focus recommends that you use this setting whenever diagnosing memory corruption.

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.

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.
  • JES Init - batch initiators, that is, SEPs that execute JCL applications.
  • JES Print - processes that handle the sending of files output by JCL jobs to printers.
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.

Job Number, Job Name

This column shows the job number and the job name of the JCL job that the SEP is handling.

Job Count, Step Name, User ID

This column shows the number of jobs this SEP has run since it was started, the step name currently being executed and the user ID under which the job is running. If you did not specify a USER on the JOB card, the user ID is the name of the enterprise server.

SYSOUT Classes, Duration

This column shows the classes that the batch printer SEP handles and the amount of time the SEP has been running.

Job Count, DD Name

This column shows the number of jobs this SEP has run since it was started, and the DD name of the file being printed.

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.

Trace

Click this to view a local trace for the associated process. This is available only for MQ listeners.

Process ID

Shows the process ID of the client.

Type

Shows the type of client:

  • 3270
  • 3270 Bridge
  • 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
  • IBM MQ - IBM Message Queuing listener
  • 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
  • TN3270 - A Telnet 3270 client
  • 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

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

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.

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

  • Services
  • iFileshare
  • Active
  • ESMAC
  • by Group
  • by StartL
  • by Type
  • JES
  • IMS
  • Pages for Creating Resources
  • Pages for Viewing and Editing Resources
Parent topic: Enterprise Server Monitor and Control (ESMAC)


Services

  • Lists of Services
  • Details of Individual Services
Parent topic: Resources


Lists of Services

  • Services
  • Service Packages
  • Request Handlers
Parent topic: Services


Services

Use this page to view information about the services currently available on the server.

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.

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.

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

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

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.

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.

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


iFileshare

Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.
  • iFSView
  • Control
Parent topic: Resources


iFSView

Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.

iFSView is the FSView interface for iFileshare servers, allowing you to view information on the current server.

help
Displays a list of iFSView commands that can be entered directly into the free-text box to the right of the Enter button.
server get
Gets the server information for the iFileshare server, such as its name, the date/time it was started, and the tracing status.
users get
Gets a list of users currently logged on to the iFileshare server.
files get
Gets a list of files currently open on the iFileshare server.
stats get
Gets a list of statistics for user and file usage, for the iFileshare server.
dump
Creates debug diagnostics for the iFileshare server.
Parent topic: iFileshare


Control

Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.

This page contains statistics about the current iFileshare high availability group, if applicable. If the current region is a standby server within a high availability group, there are options to allow you to promote the standby server to the role of primary server. You would usually require this when a manual failover is required; that is, the group consists of a primary server and one standby server, and there is a problem with the primary server.

Force Takeover
Use this option to initiate the manual failover process for an iFileshare high availability group.
Force Active
This option is still under development.
Confirm
Use this option to confirm initiation of the options above.
Parent topic: iFileshare
Related tasks
The Failover Recovery Process


Active

  • Lists of Active Resources
  • Details of an Active Resource
Parent topic: Resources


Lists of Active Resources

  • ACEEs (Active)
  • DCT (Active)
  • FCT (Active)
  • ICE (Active)
  • JCT (Active)
  • Locks (Active)
  • PCT (Active)
  • PPT (Active)
  • SysC (Active)
  • T-TYPE (Active)
  • XAT (Active)
  • TST (Active)
  • URIMAP (Active)
  • TCPIPSv (Active)
  • DOCTEMPLATE (Active)
  • TRANCLASS (Active)
  • PIPELINE (Active)
  • WEBSERVICE (Active)
  • RNL (Active)
Parent topic: Active


ACEEs (Active)

Use this page to view the list of Access Control Environment Elements (ACEE).

Details

Click to display detailed information for the ACEE.

The rest of the information in this row shows:

  • The name of the ACEE.
  • The group to which this ACEE belongs.
Note: The display is a historical list of users that have logged in from the time the region was started; it is not a reflection of the users that are currently logged in.
Parent topic: Lists of Active Resources


DCT (Active)

Use this page to view the DCTs available on this server.

Details

Click this to display detailed information for the DCT.

The rest of the information in this row shows:

  • The name of the DCT.
  • Whether the DCT is enabled or disabled.
  • The type of DCT.
Parent topic: Lists of Active Resources


FCT (Active)

Use this page to view the FCTs available on this server.

Details

Click this to display detailed information for the FCT.

The rest of the information in this row shows:

  • The name of the FCT.
  • Whether the FCT is enabled or disabled.
Parent topic: Lists of Active Resources


ICE (Active)

Use this page to view and delete the interval control elements active on this server.

You can delete an interval control element by clicking Delete button to the left of its row in the table.

Request ID

Shows the ID of the request for a time-delayed event. This is specified in the CICS API call that initiated the interval control element.

Transaction

Shows the transaction in which the call was executed.

Terminal

Shows the terminal where the transaction was entered.

Day/Time

Shows the day and time for which the time-delayed event is scheduled. Day 0 means today, day 1 means tomorrow, etc.

Parent topic: Lists of Active Resources


JCT (Active)

Use this page to view the JCTs active on this server.

Details

Click this to view detailed information for the JCT.

The rest of the information in this row shows:

  • The name of the JCT.
  • The status of the JCT.
  • The type of JCT.
Parent topic: Lists of Active Resources


Locks (Active)

Use this page to view the current resource locks on this server.

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
Parent topic: Locks


PCT (Active)

Use this page to view the PCTs available on this server.

(Details)

Click this icon to view detailed information for the PCT.

The rest of the information in this row shows:

  • The name of the PCT.
  • The average time it takes for the transaction to complete.
  • The number of times the transaction has been executed since the server started.
Parent topic: Lists of Active Resources


PPT (Active)

Use this page to view the PPTs available on this server.

Details

Click this to display detailed information for the PPT.

The rest of the information in this row shows:

  • The name of the PPT.
  • The type of PPT.
  • Whether the PPT is enabled or disabled.
  • The programming language of the program associated with the PPT.
Parent topic: Lists of Active Resources


SysC (Active)

Use this page to view the SysCs active on this server. A SysC is a definition of a CCI system connection.

Details

Click this to view detailed information for the SysC.

The rest of the information in this row shows:

  • The name of the SysC.
  • The status of the SysC.
  • The type of SysC.
Parent topic: Lists of Active Resources


T-TYPE (Active)

Use this page to view the T-types active on this server.

Details

Click to display detailed information for the T-type.

The rest of the information in this row shows:

  • The name of the T-type.
  • The status of the T-type.
  • The type of T-type.
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.

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


TST (Active)

Use this page to:

  • View the TSTs active on this server
  • View and delete the actual data queues in the TSTs
  • View and delete data records associated with interval control elements. These are held as special single-record TS queues.
Details

Click this to view detailed information for the TST.

The rest of the information in this row shows:

  • The name of the TST.
  • The status of the TST.
  • A description of the TST.
TS Unit Table Queues

Shows the actual data queues and interval control element data records that currently exist on this server. Hexadecimal IDs (those that contain non-displayable characters) are displayed in both hexadecimal notation and display notation (with the non-displayable characters replaced with full stop characters “.”).

You can delete an entry in the TS Unit Table by clicking Delete button to the left of its row in the table. When you delete an IC (interval control element) data record, you also delete the interval control element that it is associated with. The delete request is actioned immediately, and a message comfirming this is displayed at the top of the TST information.

Current

Shows the position in the queue of this item. It is used to resolve which queue item a generic READQ will return.

Depth

Shows the current number of items in the queue.

Type

Shows the type of data queue or interval control element data record. The meanings of the abbrevations are:

rc
recoverable
nr
unrecoverable
TS
temporary storage queue
IC
interval control element
Parent topic: Lists of Active Resources


URIMAP (Active)

Use this page to view the URIMAPs available on this server.

Details
Click this to display detailed information for the URIMAP.

The rest of the information in this row shows and the name of the URIMAP, whether the URIMAP definition is for an HTTP server or client, and whether it is enabled or disabled.

Parent topic: Lists of Active Resources


TCPIPSv (Active)

Use this page to view the TCPIPServices available on this server.

Details
Click this to display detailed information for the TCPIPService.

The rest of the information in this row shows the name of the TCPIPService and its current status.

Parent topic: Lists of Active Resources


DOCTEMPLATE (Active)

Use this page to view the DOCTEMPLATEs available on this server.

Details
Click this to display detailed information for the DOCTEMPLATE.

The rest of the information in this row shows the name of the DOCTEMPLATE and the type of its source.

Parent topic: Lists of Active Resources


TRANCLASS (Active)

Use this page to view the TRANCLASS resources active on this server.

Details

Click this to view detailed information for the TRANCLASS

The rest of the information in this row shows:

  • The name of the class
  • Whether or not it is enabled
Parent topic: Lists of Active Resources


PIPELINE (Active)

Use this page to view the PIPELINE resources available on this server.

Details
Click this to display detailed information for the PIPELINE.

The rest of the information in this row shows the name of the PIPELINE, whether the PIPELINE is enabled or disabled, whether it is a Provider or Requester PIPELINE and the SOAP version.

Parent topic: Lists of Active Resources


WEBSERVICE (Active)

Use this page to view the WEBSERVICE resources available on this server.

Details
Click this to display detailed information for the WEBSERVICE.

The rest of the information in this row shows the name of the WEBSERVICE, whether the WEBSERVICE is enabled, disabled or unusable, and its associated PIPELINE and URIMAP.

Parent topic: Lists of Active Resources


RNL (Active)

Restriction: Only relevant in an Enterprise Server Cluster environment.

A resource name list (RNL) is equivalent to global resource sharing (GRS). In an Enterprise Server CLUSTER these RNLs are used to determine how to treat the resources referenced by these RNLs. All RNLs are defined in the RNL descriptor file (ESCLRNLs.cfg) . At the start up of the Global Lock Manager (GLM) region, RNLs are verified and loaded in the GLM and pushed to all cluster participants during the initial cluster handshake. Once these initial definitions are installed, the RNLs can be updated on the GLM only by using the ACTIVE page. The GLM will push the changes to all cluster participants.

See RNL Support for more information on RNLs.

Use this page to view the RNLs available in this Enterprise Server Cluster member.

Details
Click this to display detailed information for the RNLs.

The information in this row displays the entire RNL definition:

Sequence
Indicates the position of this RNL in the global RNLs list.
RNL
Set to Include or Exclude.
  • Include - The SYSTEM inclusion RNL lists SYSTEM scope resources that you want the system to treat as global resources.
  • Exclude - The SYSTEMS exclusion RNL lists SYSTEMS scope resources that you want GRS to treat as local resources.

If an INCLUDE RNL matches the RNAME, the EXCLUDE list is searched, for example:

RNLDEF RNL(INCL) TYPE(Pattern) QNAME(SYSDSN) RNAME(SYS1.*)
RNLDEF RNL(EXCL) TYPE(GENERIC) QNAME(SYSDSN) RNAME(SYS1.PRD2)

Any file starting with SYS1.* would be treated as a global resource except for a file starting with SYS.PRD2.

Type

Specifies the type of resource name entry being defined in the RNL:

  • Specific - you must specify a QNAME (major name) and an RNAME (minor name) for the resource.
  • Generic - indicates that the resource name in the RNL is a generic criteria, for example:
    RNLDEF RNL(INCL) TYPE(GENERIC) QNAME(SYSDSN) RNAME(SYS1.PRD2)

    Means that all files starting with SYS1.PROD2 will be a GLOBAL resources.

  • Pattern - indicates that the resource name in the RNL entry is a pattern that must fit the resource name specified on the ENQ request.
    You can use wildcard characters (* or ?) in either part of the resource name:
    *
    Allows matching for a substring of any characters and for any length, including zero.
    ?
    Allows matching for any single character.
QNAME
Set to SYSDSN.
RName
Resource name target of the include or exclude lock.
Parent topic: Lists of Active Resources


Details of an Active Resource

  • ACEE for Username
  • DCT Entry (dct_name)
  • FCT Entry (fct_name)
  • JCT Entry (jct_name)
  • PCT Entry (pct_name)
  • PPT Entry (ppt_name)
  • SysC Entry (sysc_name)
  • T-TYPE Entry (ttype_name)
  • XAT
  • TST Entry (tst_name)
  • URIMAP Entry (urimap_name)
  • TCPIPService Entry (tcpipsv_name)
  • DOCTEMPLATE Entry (doctemplate_name)
  • TRANCLASS Entry (trnclass_name)
  • PIPELINE Entry (pipeline_name)
  • WEBSERVICE Entry (webservice_name)
  • RNL (RNL_sequence_number)
Parent topic: Active


ACEE for Username

Use this page to view the Access Control Environment Element (ACEE) for a user.

ACEE

This is the id of a user who signed on to the system.

Group

The sign-on group of the user.

Long Name

The long name of the user.

Operator ID

The identification code that you assign to the operator.

Timeout

The time in minutes that the system will allow an ESMAC or TN3270 terminal to client session to remain idle before logging off the user. If the value is 0, the system value is used.

Operator Class

The operator class used for routing messages initiated in a CICS transaction.

Priority

The value used by the system to determine task priority for CICS transactions invoked by the user at a terminal.

Resource Keys
All

Choose a setting to apply to all the resource keys:

  • On - enables all the resource keys.
  • Off - disables all the resource keys.
1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Security Keys
All

Choose a setting to apply to the security keys:

  • On - enables all the security keys.
  • Off - disables all the security keys.
1 - 64

Check any of the boxes 1 through 64 to activate that security key.

Surrogate Keys
All

Choose a setting to apply to all the surrogate keys:

  • On - enables all the surrogate keys
  • Off - disables all the surrogate keys
1 - 24

Check any of the boxes 1 through 24 to activate that surrogate key.

JCL Submit

Check this to enable this user to submit JCL jobs via the cassub utility.

ES Security

Check this for the user ID mfuser to enable ESMAC security.

ESMAC Access
all

Choose a setting for the level of access the user will have to all types of resource:

  • Rd - sets all items to read access
  • Upd - sets all items to update access
  • No - denies access for all items
Master Flag

Check this to enable the user to access the main ESMAC screens. If unchecked, the user will only be able to view summary server information and environment variables.

JES - IMS

Choose what type of access this user can have to a resource of this type:

  • Rd - sets the item to read access
  • Upd - sets the item to update access
  • No - sets the item to no access
Dump Display, Table

Click this to create and view a dump of the ACEE.

Parent topic: Details of an Active Resource


DCT Entry (dct_name)

Use this page to view information about the DCT named dct_name, selected from the DCT (Active) page. You can also view a dump of the DCT.

This page mainly provides information about the DCT. To set values for the DCT, use the CICS DCT page.

Apply

Click this to save changes you have made to the page and refresh the page.

DCT

Shows the name of this DCT. If you click Apply, the message "Update complete" is also displayed when the changes you have made to the DCT have been saved and the DCT updated. Click Refresh to remove this message.

Resource Keys
all

Choose a setting to apply to all the resource keys:

  • On - enables all the resource keys.
  • Off - disables all the resource keys.
1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Dump Display, Table

Click this to create and view a dump of the DCT.

Parent topic: Details of an Active Resource


FCT Entry (fct_name)

Use this page to view information about the FCT named fct_name, selected from the FCT (Active) page. You can view information about the FCT, and change the status of the FCT.

This page mainly provides information about the FCT. To set values for the FCT, use the CICS FCT page.

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 FCT.

FCT

Shows the name of this FCT. If you click Apply, the message "Update complete" is also displayed when any changes you have made to the FCT have been saved and the FCT updated. Click Refresh to remove this message.

Dataset Name

Shows the data set name for this file as used on the mainframe.

Status

Shows information about the current state of the file. This includes not only the current setting of Status as shown on the CICS FCT page and the CICS FCT - fct_name (grp_name) page, but also the Access fields and a subset of the Set fields.

The first item of information is the open/closed status. This is a transient state a transient state controlled by the system. Possible values are:

  • Open
  • Closed
  • Opening
  • Closing
  • CloseRequest - a request to close the file has been issued by an application
Enabled/Disabled/Unenabled

Indicates whether the file is currently accessible to transactions:

  • Enabled - the file is currently accessible to transactions.
  • Disabled - the file is not currently accessible to transactions. A disabled file returns the reference "DISABLED". This can cause problems for some applications; if this is true for your application, set Unenabled instead.
  • Unenabled - the file is not currently accessible to transactions. An unenabled file returns a reference "NOTOPEN", which can be handled by those applications that cannot handle a "DISABLED" reference.

You can change this setting on this page.

Disabling

Yes indicates that the file is currently being disabled. Disabling is a transient state controlled by the system.

Start Empty

Yes indicates that the current contents of the file are deleted at system startup.

Recoverable

Yes indicates that the file is a protected resource, changes to which can be backed out.

The file must be accessed through a Fileshare server.

Forward Recoverable

Yes indicates that journals are used to record changes to the file to enable forward recovery.

The file must be accessed through a Fileshare server.

Readable

If checked, indicates that users can read records from the file. You can change this setting.

Addable

If checked, indicates that users can add records to the file. You can change this setting.

Browsable

If checked, indicates that users can browse the file. You can change this setting.

Deletable

If checked, indicates that users can delete records from the file. You can change this setting.

Updatable

If checked, indicates that users can update records in the file. You can change this setting.

Exclusive

If checked, indicates that the file cannot be read by other transactions while an update is in progress. You can change this setting.

Type

Shows the file type. This can be one of:

  • KSDS Variable ASCII - Key sequence data set
  • ESDS - Entry sequence data set
  • RRDS - Relative record data set
  • Alternate to fct_name type - Alternate index. fct_name tells you the FCT for which this is an alternate index, and type describes the type of file represented by fct_name.
  • Undefined - Remote file
Record

Shows the maximum and minimum lengths possible for a record.

Key

Shows the length and starting position of the key.

Resource Group

Shows which resource group this FCT belongs to.

Use Count

Shows the number of times this FCT has been used.

Dump Display, Table

Click this to create and view a dump of this FCT.

Parent topic: Details of an Active Resource


JCT Entry (jct_name)

Use this page to view information about the JCT named jct_name, selected from the JCT (Active) page. You can also display a dump of the JCT.

This page mainly provides information about the JCT. To set values for the JCT, use the CICS JCT page.

Apply

Click this to save changes you have made to the page and refresh the page.

JCT

Shows the name of this JCT. If you click Apply, the message "Update complete" is also displayed when the changes you have made to the JCT have been saved and the JCT updated. Click Refresh to remove this message.

Dump Display, Table

Click this to create and view a dump of the JCT.

Parent topic: Details of an Active Resource


PCT Entry (pct_name)

Use this page to view information about the PCT named pct_name, selected from the PCT (Active) page. You can also change the status of the PCT, and change various parameters of the PCT.

This page mainly provides information about the PCT. To set values for the PCT, use the CICS PCT page.

Click Apply 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 PCT.

PCT

Shows the name of this PCT. If you click Apply, the message "Update complete" is also displayed when the changes you have made to the PCT have been saved and the PCT updated. Click Refresh to remove this message.

Program Name

Shows the program name of a local program to be run when this transaction is invoked.

TRANCLASS

Shows the transaction class for this transaction.

Default BREXIT

Shows the current bridge exit for this transaction. You can change the name of the bridge exit to be called when this transaction is invoked.

Status
Shows the current settings that apply to this transaction. You can change any of the settings.
Enabled
Click this to enable the program.
Disabled
Click this to disable the program.
UC Translation

Check this to have the transaction program translate input into upper case.

Screen Default

Click this to have the transaction program use the default screen size (as defined in the Typeterm entry).

Screen Alternate

Click this to have the transaction program use the alternate screen size (as defined in the Typeterm entry).

DTB Backout

Click this to indicate that if a transaction program using intersystem communication abends at a critical moment during syncpoint or abend processing, the effects of the transaction are backed out using ROLLBACK. To use this option, files used by the transaction program must have Backward Recovery checked on the CICS FCT page.

DTB Commit

Click this to indicate that if a transaction program using intersystem communication abends at a critical moment during syncpoint or abend processing, any changes are committed.

DTB Wait

Click this to indicate that if a transaction program using intersystem communication abends at a critical moment during syncpoint or abend processing, critical resources are locked until the session has recovered, and are then backed out or committed in step with the remote system.

Dump on Abend

Check this to indicate that a program dump is to be created if the transaction program abends.

Type

Indicates whether the program is local or remote. If the program is remote, the system and transaction IDs are also displayed.

Transaction
TWA Size
Shows the size of the transaction program's Transaction Working Area (TWA) in bytes.
Input Timeout

The maximum time in seconds allowed for operator response to an explicit CICS RECEIVE, WEB OPEN, WEB SEND, WEB RECEIVE, or WEB CONVERSE command before this transaction is abended. A value of 0 indicates that there is no timeout, and the system will wait indefinitely for a response.

Runaway Timeout

The maximum continuous period of time in seconds that the region will allow a transaction to run without making a CICS, EZASOKET or WebSphere MQ API call. When this time is exceeded, the transaction is abended. A value of 0 indicates that there is no timeout.

Deadlock Timeout

Shows the deadlock timeout used for task processing. This is the period after which a suspended task is terminated. A zero value means that no deadlock timeout is used.

Transaction Threshold

Specify the maximum length of time in seconds that a transaction can run before a message is logged to the console to indicate that it has exceeded its threshold. A value of 0 indicates that there is no threshold.

Tracing

Indicates the type of tracing set for this transaction. You can also change the type of tracing by clicking one of the buttons:

  • Standard - standard tracing is performed
  • Suppress - no tracing is performed
  • Special - special tracing is performed
Priority

Shows the transaction's priority.

Use Count

Shows the number of times this transaction has been used.

Avg. Duration

Shows the average execution time in seconds for this transaction.

Dump Display, Table

Click this to create and view a dump of the PCT.

Parent topic: Details of an Active Resource


PPT Entry (ppt_name)

Use this page to view information about the PPT named ppt_name, selected from the PPT (Active) page. You can also change the status of the PPT, and change various parameters of the PPT.

This page mainly provides information about the PPT. To set values for the PPT, use the CICS PPT page.

Apply

Click this to save changes you have made to the page and refresh the page.

PPT

Shows the name of this PPT. If you click Apply, the message "Update complete" is also displayed when the changes you have made to the PPT have been saved and the PPT updated. Click Refresh to remove this message.

Load Module

Shows the location and name of the executable file in use. You see an entry in this field only after the executable file has been used.

Status

Shows the current settings that apply to this PPT. You can change any of the settings.

Enabled

Click this to enable the PPT.

Disabled

Click this to disable the PPT.

DPL API Subset

Check this to limit the program to the Distributed Program Link API subset of commands; there is no terminal control, BMS, and so on.

CEDF Enabled

Check this to allow the use of the CICS Execution Diagnostic Facility, which enables debugging at the CICS command level.

Resident

Check this to indicate that the program resides in the application server's program cache after it has been loaded.

COBOL

Click this to indicate that the program language is COBOL.

PL1

Click this to indicate that the program language is PL/I.

C

Click this to indicate that the program language is C.

Assembler

Click this to indicate that the program language is Assembler.

WS Integrity

Check this to indicate that load requests are ignored if the program is already in storage. Leave unchecked to indicate that a fresh copy of the program is loaded every time a load request for the program is issued.

Type

Shows whether the PPT is associated with a program or data.

Size

Shows the size of the module and the minimum size of the Commarea.

Counts

Shows:

  • Resident - the number of programs resident in the server's program cache.
  • Hold Count - the number of outstanding LOAD HOLD commands that have not been countered by a RELEASE.
  • Index - the number of times a LOAD SET ENTRY() has been executed.
  • In Use Count - the number of outstanding LOAD commands that have not been countered by an exit from current units of work.
  • Reference Count
Dump Display, Table

Click this to create and view a dump of the DCT.

Parent topic: Details of an Active Resource


SysC Entry (sysc_name)

Use this page to view information about the SysC named sysc_name, selected from the SysC (Active) page. You can also display a dump of the SysC. A SysC is a definition of a CCI system connection.

This page mainly provides information about the SysC. To set values for the SysC, use the CICS SysC page.

Apply

Click this to save changes you have made to the page and refresh the page.

SysC

Shows the name of this SysC. If you click Apply, the message "Update complete" is also displayed when the changes you have made to the SysC have been saved and the SysC updated. Click Refresh to remove this message.

Dump Display, Table

Click this to create and view a dump of the SysC.

Parent topic: Details of an Active Resource


T-TYPE Entry (ttype_name)

Use this page to view information about the T-type named ttype_name, selected from the TTYPE (Active) page. You can also view a dump of the T-type.

This page mainly provides information about the T-type. To set values for the T-type, use the CICS T-type page.

Apply

Click this to save changes you have made to the page and refresh the page.

T-Type

Shows the name of this T-type. If you click Apply, the message "Update complete" is also displayed when the changes you have made to the T-type have been saved and the T-type updated. Click Refresh to remove this message.

Dump Display, Table

Click this to create and view a dump of the T-type.

Parent topic: Details of an Active Resource


XAT

Use this page to view the XATs (XA-compliant database tables) defined for the server.

Switch Module

The location of the executable file (.dll on Windows, or .so on 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


TST Entry (tst_name)

Use this page to view information about the TST named tst_name, selected from the TST (Active) page. You can also view a dump of the TST.

This page mainly provides information about the TST. To set values for the TST, use the CICS TST page.

Apply

Click this to save changes you have made to the page and refresh the page.

TST

Shows the name of this TST. If you click Apply, the message "Update complete" is also displayed when the changes you have made to the TST have been saved and the TST updated. Click Refresh to remove this message.

Dump Display, Table

Click this to create and view a dump of the TST.

Parent topic: Details of an Active Resource


URIMAP Entry (urimap_name)

Use this page to view information and set values for the URIMAP named urimap_name, selected from the URIMAP (Active) page.

Click Apply to save changes you have made to the page and refresh the page.

URIMAP
The name of this URIMAP definition. If you click Apply, the message "Update complete" is also displayed when the changes you have made to the URIMAP have been saved and the entry updated. Click Refresh to remove this message.
Usage
Specifies whether this URIMAP definition is for:
  • CICS as an HTTP server
  • CICS as an HTTP client
Status
Specifies whether this URIMAP definition is installed in an enabled or disabled state.
Analyzer
Indicates whether an analyzer program is used in processing the HTTP request.
Scheme
The scheme component of the URI.
Redirect Type
Specifies the type of redirection for requests that match this URIMAP definition, either NONE, TEMPORARY or PERMANENT.
TCPIPService
The name of a TCPIPService resource definition that defines an inbound port.
Host
The host name, or IPv4 or IPv6 address, of the URI.
Path
The path component of the URI.
Port
The number of the port used by the user application when it communicates with a server.
Transaction
The name of an alias transaction used either to run the user application that composes the HTTP response, or to start the pipeline.
Converter
The name of a converter program used to convert (or perform other processing) on the request and response.
Program
The name of the user application program that composes the HTTP response.
Pipeline
Not supported for this release.
Web Service
Not supported for this release.
User Id
Not supported for this release.
Certificate
The label of the X.509 certificate that is used as the SSL client certificate during the SSL handshake.
Ciphers
A string of up to 56 hexadecimal digits that is interpreted as a list of up to 28 2-digit cipher suite codes.
Authenticate
Specifies whether to send basic authentication information in the HTTP response to a client request.
Template Name
Not supported for this release.
HFS File
Not supported for this release.
Media Type
Not supported for this release.
Character Set
Not supported for this release.
Host Codepage
Not supported for this release.
Location
Not supported for this release.
Parent topic: Details of an Active Resource


TCPIPService Entry (tcpipsv_name)

Use this page to view information about the TCPIPService named tcpipsv_name, selected from the TCPIPSv (Active) page. You can also display a dump of the service.

This page mainly provides information about the TCPIPService. To set values for it, use the CICS TCPIPService page.

Click Apply to save changes you have made to the page and refresh the page.

TCPIPService
The name of this TCPIPService.
Status
The initial status of the service after installation, either OPEN if CICS is to begin listening for this TCPIPService after installation, or CLOSE if not.
Port
The number of the port on which CICS listens for incoming client requests.
Protocol
The application level protocol used on the TCP/IP port.
SSL Type
Indicates whether the TCPIPService is to use the secure sockets layer (SSL) for encryption and authentication.
Transaction
The ID of the CICS transaction to process new requests that this service receives.
Authenticate
The authentication and identification scheme used for inbound TCP/IP connections for the HTTP, IPIC, USER and IIOP protocols.
Backlog
Not supported for this release.
Max Data Length
Specifies the maximum length of data that may be received by CICS as an HTTP server. This value must be between 3 and 524,288 kilobytes.
URM
The name of a user-replaceable program that this TCPIPService invokes.
Privacy
The level of SSL encryption required for inbound connections.
Cipher
A list of cipher suite codes.
Host
Specifies the 116-character IPv4 or IPv6 address or host name on which this TCPIPSERVICE will listen for incoming connections.
IP Address
The IPv4 address on which this TCPIPService will listen for incoming connections.
Socket Close
How long CICS waits before closing the socket.
DNS Group
Not supported for this release.
DNS Status
The current state of Workload Manager/Domain Name System (DNS) registration of this service.
GRP Critical
Not supported for this release.
Certificate
The SSL client certificate authentication used to authenticate and identify the client.
Attach Security
Not supported for this release.
TSQ Prefix
A code to identify items in the temporary storage queue (TSQ).

Click Table to create and view a table of dump information for this service.

Parent topic: Details of an Active Resource


DOCTEMPLATE Entry (doctemplate_name)

Use this page to view information about the DOCTEMPLATE called doctemplate_name, selected from the DOCTEMPLATE (Active) page. You can also display a dump of the loaded DOCTEMPLATE in memory.

DOCTEMPLATE
The name of this template.
Append CR/LF
Indicates whether CICS deletes trailing blanks from, and appends carriage return/line feed to, each logical record of the template.
Type
The format of the template contents, either BINARY, EBCDIC or ASCII.
Template Type
The type for the source of the template, namely one of the following types.
Template Name
The name by which the template is known to application programs that use it.
File
The name of the CICS file which contains the template.
TS Queue
The name of the temporary storage queue containing the template.
TD Queue
The name of the transient storage queue containing the template.
Program
The name, of the CICS program that contains the template.
Exit Program
The name of the exit program that generates this template.
DD Name
The name of the MVS partitioned data set (PDS) containing the template. If you enter a value for Member Name but no DD Name, it defaults to "DFHHTML".
Member Name
The name of the member in the MVS partitioned data set containing the template.
HFS File
The name of the z/OS UNIX System Services file containing the template.

Click Table to create and view a table of dump information for this resource.

Parent topic: Details of an Active Resource


TRANCLASS Entry (trnclass_name)

Use this page to view information about the TRANCLASS named trnclass_name, selected from the TRANCLASS (Active) page. You can also display a dump of the TRANCLASS.

This page mainly provides information about the TRANCLASS. To set values for it, use the CICS TRANCLASS page.

Apply

Click this to save changes you have made to the page and refresh the page.

TRANCLASS

Shows the name of this TRANCLASS. If you click Apply, the message "Update complete" is also displayed when the changes you have made have been saved and the resource updated. Click Refresh to remove this message.

Status
Max Active
Purgethresh
Not currently supported.
Active
Running
Dump Display, Table

Click this to create and view a dump of the TRANCLASS.

Parent topic: Details of an Active Resource


PIPELINE Entry (pipeline_name)

Use this page to view information and set values for the PIPELINE named pipeline_name, selected from the PIPELINE (Active) page.

Apply

Click this to save changes you have made to the page and refresh the page.

PIPELINE

Shows the name of this PIPELINE definition.

Status
  • Enabled - the PIPELINE Entry is enabled.
  • Disabled - the PIPELINE Entry is disabled.
Resp Wait

Shows the number of seconds that an application should wait for a response message from the service. DEFT indicates the default value of the transport protocol. HTTP is 10 seconds. MQ is 60 seconds.

Shelf
Must reference a valid directory, but currently unused.
Cfg File
Shows a fully qualified pipeline configuration file.
WebSvc Dir
Shows a fully qualified name of the web service binding directory. When the PIPELINE is installed, this directory is scanned for .wsbind files and a WEBSERVICE resource is created and installed for each file found.
Parent topic: Details of an Active Resource


WEBSERVICE Entry (webservice_name)

Use this page to view information and set values for the WEBSERVICE named webservice_name, selected from the WEBSERVICE (Active) page.

Apply

Click this to save changes you have made to the page and refresh the page.

WEBSERVICE

Shows the name of this WEBSERVICE definition.

Status
ENABLED|UNUSABLE - if the WEBSERVICE is enabled, then the Discarded option can be checked to remove it.
Pipeline

Shows the name of the PIPELINE associated with this WEBSERVICE.

Urimap
Shows the URIMap associated with this WEBSERVICE (provider).
Program
Shows the resource name of the application program being exposed as a web service (provider only).
PGMInterface
Channel|Commarea (NOTAPPLIC for requester).
WSDL File
Shows the fully qualified location of the WSDL file (currently unused).
Archive File
Unused.
WSBIND
Shows the fully qualified location of the web service binding file.
Endpoint
Shows the endpoint in the wsdl.
Binding
Shows the value of the binding parameter in the .wsbind file.
Dynamically Installed
Yes|No - indicates whether this resource was dynamically installed via a scan of the WebSvc directory of the associated PIPELINE.
Trace SOAP application handler
Checking this option switches on tracing of each request/response in the application handler for this WEBSERVICE.
Parent topic: Details of an Active Resource


RNL (RNL_sequence_number)

Restriction: This page is only available on the GLM region.

Use this page to view information on the RNL RNL_sequence_number item selected from the RNL (Active) page.

Apply

Click this to save changes you have made to the page and refresh the page.

Sequence

Shows the position of this RNL in the global RNLs list, this is a read-only field.

RNL
Can be set to Include or Exclude.
Type

Can be set to Specific, Generic or Pattern.

QNAME
Set to SYSDSN and is a read-only field.
RName
Shows the resource name target of the include or exclude lock.

On Apply the updates will be pushed to the Enterprise Server Cluster participants.

Parent topic: Details of an Active Resource


ESMAC

  • MQ Listeners
  • MQ Writers
  • MQ Listener (listener-name)
  • MQ Writers (writer-name)
Parent topic: Resources


MQ Listeners

Use this page to view information about the MQ listeners available on the current server.

Details
Click this to display detailed information for the listener. Each detail row shows the following:
  • Name of the listener
  • Status of the listener
  • Type of listener
  • Number of messages processed
  • Number of messages that produced errors
  • Name of the MQ queue that is being listened to
Parent topic: ESMAC


MQ Writers

Use this page to view information about the dynamically created MQ writers available on the current server.

Details
Click this to display detailed information for the writer. Each detail row shows the following:
  • Name of the writer
  • Status of the writer
  • Type of writer
  • Number of messages processed
  • Number of messages that produced errors
  • Name of the MQ queue being written to
Parent topic: ESMAC


MQ Listener (listener-name)

Use this page to view information about a particular MQ listener selected from the MQ Listeners page.

Start / Stop

Starts or stops the MQ listener. Toggle.

Name
The name of the MQ listener.
Queue
The name of the MQ queue being listened to.
Queue Manager
The name of the Websphere MQ queue manager that defines the queue being listened to.
Type
The type of MQ listener.
Message Count
The number of messages processed.
Error Count
Number of messages that produced errors.
Dump
Click this to write dump information for this for this MQ listener to the casdump.rec file.
Parent topic: ESMAC
Related reference
CASDUMP


MQ Writers (writer-name)

Use this page to view information about a particular MQ writer selected from the MQ Writers page.

Stop

Stops and deletes the MQ writer.

Name
The name of the MQ writer.
Queue
The name of the MQ queue being written to.
Queue Manager
The name of the Websphere MQ queue manager that defines the queue being written to.
Type
The type of MQ writer.
Message Count
The number of messages processed.
Error Count
Number of messages that produced errors.
Dump
Click this to write dump information for this MQ writer to the casdump.rec file.
Parent topic: ESMAC


by Group

  • CICS Resource Groups
  • Startup
  • SIT
Parent topic: Resources


CICS Resource Groups

Use this page to view the CICS resource groups available on this server.

New

Click this to create a new CICS resource group.

Details

Click this to view detailed information for the CICS resource group.

The rest of the information in this row shows:

  • The name of the CICS resource group.
  • A description of the CICS resource group.
  • CICS Resource Group
  • Create a New CICS Group
  • View and Edit CICS Group group_name
Parent topic: by Group


CICS Resource Group

Use this page to view the resources within the resource group name.

Details

Click this to display detailed information for the CICS resource.

The rest of the information in this row shows:

  • The name of the resource.
  • The type of resource, such as FCT or PPT.
  • A short description of the resource.
New

Click one of the buttons to create a new resource.

Parent topic: CICS Resource Groups


Create a New CICS Group

Use this page to create a new resource group.

Group List

Click this to view the group list for this group. The group list page will be empty until you have clicked Add.

Add

Click this to save changes you have made to the page, refresh the page and add the new resource group to the list of groups. The name of the button changes to Apply.

Name

Specify a name for this resource group.

Description

Specify a description for this resource group.

Parent topic: CICS Resource Groups


View and Edit CICS Group group_name

Use this page to view a resource group and to change its description.

Group List

Click this to view the group list for this group.

Apply

Click this to save changes you have made to the page and refresh the page.

Name

Shows the name of this resource group.

Description

Specify a description for this resource group.

Parent topic: CICS Resource Groups


Startup

Use this page to view the startup lists available on this server.

Details

Click this to display detailed information for the startup list.

The rest of the information in this row shows:

  • The name of the startup list
  • A short description of the startup list
  • Create a New CICS Startup List
  • View and Edit a CICS Startup List
  • CICS Startup List list_name or CICS Defined resource
Parent topic: by Group


Create a New CICS Startup List

Use this page to create a new startup list.

Add

Click this to save changes you have made to the page and refresh the page. The button changes to Apply.

Name

Specify a name for this startup list.

Description

Specify a short description of the startup list.

Entry Count

Shows the number of resource groups in this startup list.

Production

Check this to indicate that this is a production startup list. Leave this unchecked to indicate that this is a development startup list.

01

Specify the name of the first resource group in the startup list.

Parent topic: Startup


View and Edit a CICS Startup List

Use this page to view the startup list name or to edit the values on this page. This page is displayed either when you select a startup list from the CICS Startup Lists page or when you are creating a startup list and have just added the first resource group to it. You can edit the values on this page and add new resource groups only if you have the necessary permission.

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 startup list.

Name

Shows the name of the startup list.

Description

Specify a short description of the startup list.

Entry Count

Shows the number of resource groups in this startup list.

Production

Check this to indicate that this is a production startup list. leave this unchecked to indicate that this is a development startup list.

01 - nn

Lists the resource groups in the startup list.

A startup list can reference up to 64 resource groups.

To add a resource group, click in the next empty field in the list, and enter the name.

You can change the order of the resource groups in the startup list. Use Down arrow button to move a resource down the list. Use Up arrow button to move a resource up the list. Delete an entry in the resource list by clicking Delete button.

Delete

Click this to delete this startup list. You see this button only if you have permission to edit the startup list.

Copy

Click this to create a new startup list. The values on the current page will be used as the basis for the values in the new startup list.

Dump

Click this to create and view display a dump of the startup list information.

Parent topic: Startup


CICS Startup List list_name or CICS Defined resource

Use this page to view resources of a particular type.

If you displayed this page by clicking on one of the buttons displayed when you click Resources, by Start L, this page lists the resources of a particular type available to the current startup list.

If you displayed this page by clicking on one of the buttons displayed when you click Resources, by Type, this page lists the resources of a particular type available to the current server.

Details

Click this to view detailed information for the resource.

The rest of the information in this row shows:

  • The name of the resource.
  • The type of resource.
  • The group to which the resource belongs.
  • A short description of the resource.
New

Click one of the buttons to create a new resource.

Parent topic: Startup
Parent topic: by Type


SIT

Use this page to view the list of system initialization tables (SITs) defined for an enterprise server.

New

Click this to create a new SIT.

Details

Click this to view detailed information for the SIT.

The rest of the information in this row shows:

  • The name of the SIT.
  • The startup list used by the SIT.
  • A short description of the SIT.
  • Create a New CICS SIT
  • CICS SIT Details
Parent topic: by Group


Create a New CICS SIT

Use this page to create a new SIT.

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new SIT.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Name

Shows the name of the SIT.

Description

Specify a short description of the SIT. The SIT description can contain the characters A-Z, 0-9, #, @, and $.

Startup List

Choose the startup list that you want to associate with this SIT from the dropdown list. The startup list determines which resources are loaded when the server is initialized.

Work Area

Specify the size of the region's common work area (CWA) in bytes in the range 0 through 32767. This area is shared among applications running in the region (enterprise server).

SysID

Specify the system ID of the region (enterprise server). (This is the name by which it is known to other regions.)

Initial Tran ID

Specify the ID of an initial transaction that runs on every terminal when it logs on to the region.

Auto Install Exit

Specify the name of the program to be used to autoinstall terminals. Choose from:

  • DFHZATDX - the autoinstall program supplied with MSS. This is the default value.
  • user-specified - the name of your autoinstall exit program. Up to 8 characters from 0 through 9, A through Z, @, # and $. The first character must not be numeric.
Date Format

Choose the display format used to display the date. This is used in conjunction with the FULLDATE (for four-digit years) or DATE (for two-digit years) operands of the EXEC CICS FORMATTIME command. This setting only determines the order of day, month, and year; it does not prevent four digits from being displayed.

3270 Print

Check this to indicate that the region supports a printer.

3270 SNA Simulate end-bracket

Check this if you want MSS to simulate SNA end-of-transaction keyboard unlock. You might want to do this if you have migrated applications that were accessed on the mainframe from SNA devices and are now using TN3270 clients to access them. It is an alternative to specifying the free keyboard bit in the CTLCHAR operand of the SEND 3270 CICS command.

Remote 3270

Check this to indicate that when a remote CICS region handles a START request shipped to it by this CICS region, and the terminal that should be started is not defined on the remote system, the remote region should assume that the terminal is defined on the originating system and should start a terminal anyway. If you leave this unchecked, the remote system returns a TERMIDERR to the originating region.

Separators

Specify Date for the character used to separate the day, month and year components of the date. You can specify any displayable character.

Specify Time for the character used to separate the hours, minutes and seconds components of the time. You can specify any displayable character.

Addressing
Specify the format in which pointers are stored.

Native: pointers are stored in the format used by the operating system.

24: pointers are stored in a 24-bit format. This format is compatible with "below-the-line" storage on the mainframe, in which the top eight bits of the pointer are masked off when the address of a linkage item is set from the pointer. This means that the top eight bits can be manipulated directly by the user's code.

31: pointers are stored in a 31-bit format. This format is compatible with "above-the-line" storage on the mainframe, in which the top bit of the pointer is masked off when the address of a linkage item is set from the pointer. This means that the top bit can be manipulated directly by the user's code.

TCP Connect: Yes, Port

Not used.

ID Timeout

Specify the time in minutes that the system will allow an ESMAC or TN3270 client session to remain idle before logging off the user. A value of 0 indicates that there is no timeout. You can override this value at runtime by changing the ID Timeout on the ESMAC Control screen.

IBM Client

Check Yes to indicate that an IBM Universal Clients gateway is to be established when the region starts up.

Use Port to specify the TCP/IP port number to use for the Universal Clients gateway. This must match the TCP/IP port number you specify in the Universal Clients configuration file except that if you use the defaults, the value in the configuration file is 0 whereas the value here is 1435.

Use Count to specify the number of sessions you want allocated to servicing inbound requests per connection, where connection corresponds to a client machine.

Input Timeout

Specify the maximum time in seconds allowed for operator response to an explicit CICS RECEIVE command before the transaction is abended. A value of 0 indicates that there is no timeout. You can override this value at runtime by changing the Input Timeout on the ESMAC Control screen. You can also override this value for an individual transaction through the relevant Program Control Table entry.

Local Trace Entry Count (MFCS)

Specify the number of entries the local trace table for service execution processes 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.

The default is the value specified in Local Trace Size on the Server > Properties > Diagnostics page in ES Admin. If you specify a value here it overrides that value.

Runaway Timeout

Specify the maximum continuous period of time in seconds that the region will allow a transaction to run without making a CICS, EZASOKET or WebSphere MQ API call. When this time is exceeded, the transaction is abended. A value of 0 indicates that there is no timeout. You can override this value at runtime by changing the Runaway Timeout on the ESMAC Control screen. You can also override this value for an individual transaction through the relevant Program Control Table entry.

Local Trace Entry Count (AUX)

Specify the number of entries the local trace table for auxiliary processes can hold before it wraps back to the start. A value of 0 (zero) means that no local trace table is allocated. Auxiliary processes include processes that handle journal control, extra-partition transient data, etc. Each auxiliary process has its own local trace table. Each entry is 24 bytes long.

The default is the value specified in Local Trace Size on the Server > Properties > Diagnostics page in ES Admin. If you specify a value here it overrides that value.

Deadlock Timeout

Specify the maximum time in seconds that the region will permit an application to wait for a resource that has been locked by another process. A value of 0 indicates that there is no timeout. You can override this value at runtime by changing the Deadlock Timeout on the ESMAC Control screen. You can also override this value for an individual transaction through the relevant Program Control Table entry.

Transaction Threshold

Specify the maximum length of time in seconds that a transaction can run before a message is logged to the console to indicate that it has exceeded its threshold. A value of 0 indicates that there is no threshold.

The Transaction Threshold value can be overridden using the Transaction Threshold field of a PCT entry.

IBM MQ
Note: This field is now deprecated. Define the queue manager name on the MQ Listener tab.

Check this to enable support for IBM WebSphere MQ®.

The MQ Connection should be set either in XA Resource Manager or the System Initialization Table (SIT). Do not set it in both or you will have two connections between the ES region and the MQ Queue Manager. Only one is required.

Q Manager
Note: This field is now deprecated. Define the queue manager name on the MQ Listener tab.

Specify the name of the IBM WebSphere MQ® queue manager. Can be up to 48 characters.

IBM MQ CKTI
Note: This field is now deprecated. Define the queue manager name on the MQ Listener tab.

Check this to enable the transaction CKTI, which monitors the IBM WebSphere MQ® initiation queue.

Initiation Q
Note: This field is now deprecated. Define the queue manager name on the MQ Listener tab.

Specify the name of the IBM WebSphere MQ® initiation queue. Can be up to 48 characters.

Print Destination

Specify the printer destination, up to 14 characters in length. You must check 3270 Print before you specify a printer destination.

Program Lists

Use Post Initialization to specify a program list table (PLT) entry that specifies the initialization programs to be run when the region is started. If you leave this field blank then no special processing is done when the region is started.

Use Shut Down to specify a program list table (PLT) entry that specifies the shutdown programs to be run when the region is stopped. If you leave this field blank then no special processing is done when the region is stopped.

Fileshare

Check this to create a dedicated Fileshare server process as part of region startup.

Fileshare User

Specify the user ID to be used by the region to log on to all Fileshare servers that MSS is configured to use. Can be up to 20 characters. You should specify a user ID only if Fileshare security is enabled. If you specify a user ID, you must also specify a password in Password. The user ID and password combination must correspond to an entry in the password file of each Fileshare server the region is to access.

Password

Specify the 20-character password used in conjunction with User ID to log on to all Fileshare servers that MSS is configured to use. There are two password fields; you need to enter the password in both fields, and the two entries must match. Can be up to 20 characters.

Ext. Shutdown

Choose the type of external shutdown that you want. An external shutdown is a shutdown of the server initiated by you clicking Shutdown on the Control page, Stop Server on the Enterprise Server Administration Server Details page, or issuing a casstop command. You can choose from:

  • Allowed: no special privileges are required
  • Logon: a successful logon must be made first
  • None: no external shutdown is allowed
Note: If you choose Logon, you cannot shut down the server by clicking Stop Server on the Enterprise Server Administration Server Details page. You must use casstop and must supply an ESMAC user ID and password.
Ext. Shutdown, Security Key

Specify a security key number. MSS checks this against the shutdown security key specified when you shut down the region. You need to specify a security key number only if you choose Logon in External Shutdown.

CICS Release

Choose the version of CICS that MSS is emulating. This is the number returned by an EXEC CICS INQUIRE SYSTEM RELEASE () command.

Program

Check this to have MSS reload programs each time they are invoked. This applies only to programs that are not marked resident and have not been loaded with the hold attribute.

Development SIT

Check this to indicate that this is a development SIT. The effect of this is:

  • If you have defined a group with the same name as the SIT, the group is automatically added to the startup list
  • Security is turned off even if the group has security turned on
Terminal

Check this to have MSS wait on each terminal control or BMS SEND operation until it receives a response. If you leave the box unchecked (the default) MSS does not wait on each SEND, thus enabling terminal control and send operations to be buffered, which improves performance.

Commarea

Specify the minimum amount of storage to be allocated to the communications area (COMMAREA) to allow MSS to behave like mainframe CICS. The size is in the range 0 through 32767. The effect of this is that when a program is passed a COMMAREA smaller than the COMMAREA defined in the program, the passed COMMAREA is automatically extended in length to fill the defined space.

Defer Install

Choose the number of PCT groups whose loading you want to defer.

If you choose None, all PCT entries are loaded into memory when the region starts up. This is the default.

If you choose All groups, none of the PCT entries are loaded into memory when the region starts up.

If you choose one of the other values, Last 63 groups, Last 62 groups and so on, the PCT entries in those groups are not loaded into memory when the region starts up. For example, if you choose Last 3 groups, the last three groups in the startup list's precedence order are not loaded into memory when the region starts up.

Dump On, Abend

Check this to indicate that MSS should produce a dump if an abend occurs in any of your transaction programs. If you check this field, then you can control whether or not a dump is produced for an individual program by checking or unchecking Dump on ABEND on the PCT page. If you leave this field unchecked, MSS ignores the setting of Dump on ABEND on the PCT page.

Dump On, System Abend

Check this to indicate that MSS should produce a dump if an abend occurs in its own code.

Aux Trace

Check this to indicate that trace records are to be written to a file. You should do this only if you have adequate disk space available, since the file can become very big very quickly. Writing out to a file also degrades performance.

Cold Start

Check this to indicate that the auxiliary trace and dump file is to be deleted at region startup.

Trace Points
all

Choose a setting to apply to all the trace points:

  • On - enables all trace points.
  • Off - disables all trace points.
Note: 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 Foucs.
Server
dmp

Check this to indicate that MSS is to trace its dump control component.

tcp

Check this to indicate that MSS is to trace its terminal control component.

tmp

Check this to indicate that MSS is to trace its table management component.

exits

Check this to indicate that MSS is to trace the user exits.

fh-enable

Do not check this unless advised by Micro Focus.

msg

Check this to indicate that MSS is to trace its messages component.

fh

Do not check this unless advised by Micro Focus.

jcp

Check this to indicate that MSS is to trace its journal control component.

scp

Check this to indicate that MSS is to trace its storage control component.

CICS
api

Check this to indicate that MSS is to trace the CICS API calls.

icp

Check this to indicate that MSS is to trace its interval control component.

ts-td

Check this to indicate that MSS is to trace its temporary storage/transient data (TS/TD) component.

fcp

Check this to indicate that MSS is to trace its file control component.

kcp

Check this to indicate that MSS is to trace its task control component.

user

Check this to enable user trace.

Communications
cci

Do not check this unless advised by Micro Focus.

comms

Check this to indicate that MSS is to trace its communications component.

Temp. Storage

Check Cold Start to indicate that MSS should reset temporary storage queues at region startup.

Specify a Fileshare server ID for non-recoverable temporary storage queues.

Path (nr)

Specify the path for non-recoverable temporary storage queues.

Recoverable (recoverable temporary storage queues)

Check Cold Start to indicate that MSS should reset temporary storage queues at region startup.

Specify a Fileshare server ID for recoverable temporary storage queues.

Path (rc)

Specify the path for recoverable temporary storage queues.

Transient Data

Check Cold Start to indicate that MSS should reset transient data queues at region startup.

Specify a Fileshare server ID for non-recoverable transient data queues.

Check Require Def. to indicate that a transaction program executing in this region can write to a transient data queue only if it has been defined in the destination control table (DCT). If this option is not checked, when a program attempts to write to a TDQ that has not been defined in the DCT, CICS will create a non-recoverable intra-partition TDQ that has no transaction associated with it. This may result in unexpected program and/or system behaviour if the intention was to write to a pre-defined TDQ of a similar name. We recommend that this option is always checked.

Path (rc)

Specify the path for recoverable temporary storage queues.

Recoverable (recoverable transient data queues)

Check Cold Start to indicate that MSS should reset transient data queues at region startup.

Specify a Fileshare server ID for recoverable transient data queues.

Path (nr)

Specify the path of for non-recoverable temporary storage queues.

Basic Mapping Page Commands

Use Retrieve to specify the character string that BMS control is to interpret as the BMS paging command RETRIEVE.

Use Chain to specify the character string that BMS control is to interpret as the BMS paging command CHAIN

Use Purge to specify the character string that BMS control is to interpret as the BMS paging command PURGE

Use Copy to specify the character string that BMS control is to interpret as the BMS paging command COPY

Single Key

For each key from PF1 through PF24 and PA1 through PA3, specify a character string on the PC that is to equate to a BMS paging command.

Parent topic: SIT


CICS SIT Details

Use this page to view the details for the System Initialization Table (SIT) named sit_name. If you have the required permissions, you can also:

  • Edit the configurable settings of the current SIT
  • Delete the current SIT
  • Create a new SIT, based on the settings in this SIT

Click Apply to save changes you make to the page. This button is displayed only if you have permission to edit the SIT.

Name

Shows the name of the SIT.

Description

Specify a short description of the SIT. The SIT description can contain the characters A-Z, 0-9, #, @, and $.

Startup List

Choose the startup list that you want to associate with this SIT from the dropdown list. The startup list determines which resources are loaded when the server is initialized.

Work Area

Specify the size of the region's common work area (CWA) in bytes in the range 0 through 32767. This area is shared among applications running in the region (enterprise server).

SysID

Specify the system ID of the region (enterprise server). (This is the name by which it is known to other regions.)

Initial Tran ID

Specify the ID of an initial transaction that runs on every terminal when it logs on to the region.

Auto Install Exit

Specify the name of the program to be used to autoinstall terminals. Choose from:

  • DFHZATDX - the autoinstall program supplied with MSS. This is the default value.
  • user-specified - the name of your autoinstall exit program. Up to 8 characters from 0 through 9, A through Z, @, # and $. The first character must not be numeric.
Date Format

Choose the display format used to display the date. This is used in conjunction with the FULLDATE (for four-digit years) or DATE (for two-digit years) operands of the EXEC CICS FORMATTIME command. This setting only determines the order of day, month, and year; it does not prevent four digits from being displayed.

3270 Print

Check this to indicate that the region supports a printer.

3270 SNA Simulate end-bracket

Check this if you want MSS to simulate SNA end-of-transaction keyboard unlock. You might want to do this if you have migrated applications that were accessed on the mainframe from SNA devices and are now using TN3270 clients to access them. It is an alternative to specifying the free keyboard bit in the CTLCHAR operand of the SEND 3270 CICS command.

Remote 3270

Check this to indicate that when a remote CICS region handles a START request shipped to it by this CICS region, and the terminal that should be started is not defined on the remote system, the remote region should assume that the terminal is defined on the originating system and should start a terminal anyway. If you leave this unchecked, the remote system returns a TERMIDERR to the originating region.

Separators

Specify Date for the character used to separate the day, month and year components of the date. You can specify any displayable character.

Specify Time for the character used to separate the hours, minutes and seconds components of the time. You can specify any displayable character.

Addressing
Specify the format in which pointers are stored.

Native: pointers are stored in the format used by the operating system.

24: pointers are stored in a 24-bit format. This format is compatible with "below-the-line" storage on the mainframe, in which the top eight bits of the pointer are masked off when the address of a linkage item is set from the pointer. This means that the top eight bits can be manipulated directly by the user's code.

31: pointers are stored in a 31-bit format. This format is compatible with "above-the-line" storage on the mainframe, in which the top bit of the pointer is masked off when the address of a linkage item is set from the pointer. This means that the top bit can be manipulated directly by the user's code.

TCP Connect: Yes, Port

Not used.

ID Timeout

Specify the time in minutes that the system will allow an ESMAC or TN3270 client session to remain idle before logging off the user. A value of 0 indicates that there is no timeout. You can override this value at runtime by changing the ID Timeout on the ESMAC Control screen.

IBM Client

Check Yes to indicate that an IBM Universal Clients gateway is to be established when the region starts up.

Use Port to specify the TCP/IP port number to use for the Universal Clients gateway. This must match the TCP/IP port number you specify in the Universal Clients configuration file except that if you use the defaults, the value in the configuration file is 0 whereas the value here is 1435.

Use Count to specify the number of sessions you want allocated to servicing inbound requests per connection, where connection corresponds to a client machine.

Input Timeout

Specify the maximum time in seconds allowed for operator response to an explicit CICS RECEIVE command before the transaction is abended. A value of 0 indicates that there is no timeout. You can override this value at runtime by changing the Input Timeout on the ESMAC Control screen. You can also override this value for an individual transaction through the relevant Program Control Table entry.

Local Trace Entry Count (MFCS)

Specify the number of entries the local trace table for service execution processes 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.

The default is the value specified in Local Trace Size on the Server > Properties > Diagnostics page in ES Admin. If you specify a value here it overrides that value.

Runaway Timeout

Specify the maximum continuous period of time in seconds that the region will allow a transaction to run without making a CICS, EZASOKET or WebSphere MQ API call. When this time is exceeded, the transaction is abended. A value of 0 indicates that there is no timeout. You can override this value at runtime by changing the Runaway Timeout on the ESMAC Control screen. You can also override this value for an individual transaction through the relevant Program Control Table entry.

Local Trace Entry Count (AUX)

Specify the number of entries the local trace table for auxiliary processes can hold before it wraps back to the start. A value of 0 (zero) means that no local trace table is allocated. Auxiliary processes include processes that handle journal control, extra-partition transient data, etc. Each auxiliary process has its own local trace table. Each entry is 24 bytes long.

The default is the value specified in Local Trace Size on the Server > Properties > Diagnostics page in ES Admin. If you specify a value here it overrides that value.

Deadlock Timeout

Specify the maximum time in seconds that the region will permit an application to wait for a resource that has been locked by another process. A value of 0 indicates that there is no timeout. You can override this value at runtime by changing the Deadlock Timeout on the ESMAC Control screen. You can also override this value for an individual transaction through the relevant Program Control Table entry.

Transaction Threshold

Specify the maximum length of time in seconds that a transaction can run before a message is logged to the console to indicate that it has exceeded its threshold. A value of 0 indicates that there is no threshold.

The Transaction Threshold value can be overridden using the Transaction Threshold field of a PCT entry.

IBM MQ
Note: This field is now deprecated. Define the queue manager name on the MQ Listener tab.

Check this to enable support for IBM WebSphere MQ®.

See Configuring Enterprise Server for IBM WebSphere MQ for more information.

Q Manager
Note: This field is now deprecated. Define the queue manager name on the MQ Listener tab.

Specify the name of the IBM WebSphere MQ® queue manager. Can be up to 48 characters.

IBM MQ CKTI
Note: This field is now deprecated. Define the queue name on the MQ Listener tab.

Check this to enable the transaction CKTI, which monitors the IBM WebSphere MQ® initiation queue.

Initiation Q
Note: This field is now deprecated. Define the queue name on the MQ Listener tab.

Specify the name of the IBM WebSphere MQ® initiation queue. Can be up to 48 characters.

Print Destination

Specify the printer destination, up to 14 characters in length. You must check 3270 Print before you specify a printer destination.

Program Lists

Use Post Initialization to specify a program list table (PLT) entry that specifies the initialization programs to be run when the region is started. If you leave this field blank then no special processing is done when the region is started.

Use Shut Down to specify a program list table (PLT) entry that specifies the shutdown programs to be run when the region is stopped. If you leave this field blank then no special processing is done when the region is stopped.

Fileshare

Check this to create a dedicated Fileshare server process as part of region startup.

Fileshare User

Specify the user ID to be used by the region to log on to all Fileshare servers that MSS is configured to use. Can be up to 20 characters. You should specify a user ID only if Fileshare security is enabled. If you specify a user ID, you must also specify a password in Password. The user ID and password combination must correspond to an entry in the password file of each Fileshare server the region is to access.

For more information about Fileshare security, see the chapter Security in the Fileshare Guide.

Password

Specify the 20-character password used in conjunction with User ID to log on to all Fileshare servers that MSS is configured to use. There are two password fields; you need to enter the password in both fields, and the two entries must match. Can be up to 20 characters.

Ext. Shutdown

Choose the type of external shutdown that you want. An external shutdown is a shutdown of the server initiated by you clicking Shutdown on the Control page, Stop Server on the Enterprise Server Administration Server Details page, or issuing a casstop command. You can choose from:

  • Allowed: no special privileges are required
  • Logon: a successful logon must be made first
  • None: no external shutdown is allowed
Note: If you choose Logon, you cannot shut down the server by clicking Stop Server on the Enterprise Server Administration Server Details page. You must use casstop and must supply an ESMAC user ID and password.
Ext. Shutdown, Security Key

Specify a security key number. MSS checks this against the shutdown security key specified when you shut down the region. You need to specify a security key number only if you choose Logon in External Shutdown.

CICS Release

Choose the version of CICS that MSS is emulating. This is the number returned by an EXEC CICS INQUIRE SYSTEM RELEASE () command.

Program

Check this to have MSS reload programs each time they are invoked. This applies only to programs that are not marked resident and have not been loaded with the hold attribute.

Development SIT

Check this to indicate that this is a development SIT. The effect of this is:

  • If you have defined a group with the same name as the SIT, the group is automatically added to the startup list
  • Security is turned off even if the group has security turned on
Terminal

Check this to have MSS wait on each terminal control or BMS SEND operation until it receives a response. If you leave the box unchecked (the default) MSS does not wait on each SEND, thus enabling terminal control and send operations to be buffered, which improves performance.

Commarea

Specify the minimum amount of storage to be allocated to the communications area (COMMAREA) to allow MSS to behave like mainframe CICS. The size is in the range 0 through 32767. The effect of this is that when a program is passed a COMMAREA smaller than the COMMAREA defined in the program, the passed COMMAREA is automatically extended in length to fill the defined space.

Defer Install

Choose the number of PCT groups whose loading you want to defer.

If you choose None, all PCT entries are loaded into memory when the region starts up. This is the default.

If you choose All groups, none of the PCT entries are loaded into memory when the region starts up.

If you choose one of the other values, Last 63 groups, Last 62 groups and so on, the PCT entries in those groups are not loaded into memory when the region starts up. For example, if you choose Last 3 groups, the last three groups in the startup list's precedence order are not loaded into memory when the region starts up.

Dump On, Abend

Check this to indicate that MSS should produce a dump if an abend occurs in any of your transaction programs. If you check this field, then you can control whether or not a dump is produced for an individual program by checking or unchecking Dump on ABEND on the PCT page. If you leave this field unchecked, MSS ignores the setting of Dump on ABEND on the PCT page.

Dump On, System Abend

Check this to indicate that MSS should produce a dump if an abend occurs in its own code.

Aux Trace

Check this to indicate that trace records are to be written to a file. You should do this only if you have adequate disk space available, since the file can become very big very quickly. Writing out to a file also degrades performance.

Cold Start

Check this to indicate that the auxiliary trace and dump file is to be deleted at region startup.

Trace Points
all

Choose a setting to apply to all the trace points:

  • On - enables all trace points.
  • Off - disables all trace points.
Note: 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 Foucs.
Server
dmp

Check this to indicate that MSS is to trace its dump control component.

tcp

Check this to indicate that MSS is to trace its terminal control component.

tmp

Check this to indicate that MSS is to trace its table management component.

exits

Check this to indicate that MSS is to trace the user exits.

fh-enable

Do not check this unless advised by Micro Focus.

msg

Check this to indicate that MSS is to trace its messages component.

fh

Do not check this unless advised by Micro Focus.

jcp

Check this to indicate that MSS is to trace its journal control component.

scp

Check this to indicate that MSS is to trace its storage control component.

srv

Check this to indicate that MSS is to trace SEP-hosted task control functions.

CICS
api

Check this to indicate that MSS is to trace the CICS API calls.

icp

Check this to indicate that MSS is to trace its interval control component.

pcp

Check this to indicate that MSS is to trace program management functions.

ts-td

Check this to indicate that MSS is to trace its temporary storage/transient data (TS/TD) component.

fcp

Check this to indicate that MSS is to trace its file control component.

kcp

Check this to indicate that MSS is to trace its task control component.

user

Check this to enable user trace.

Communications
cci

Do not check this unless advised by Micro Focus.

common

Check this to indicate that MSS is to trace its communications component.

Temp. Storage

Check Cold Start to indicate that MSS should reset temporary storage queues at region startup.

Specify a Fileshare server ID for non-recoverable temporary storage queues.

Path (nr)

Specify the path for non-recoverable temporary storage queues.

Recoverable (recoverable temporary storage queues)

Check Cold Start to indicate that MSS should reset temporary storage queues at region startup.

Specify a Fileshare server ID for recoverable temporary storage queues.

Path (rc)

Specify the path for recoverable temporary storage queues.

Transient Data

Check Cold Start to indicate that MSS should reset transient data queues at region startup.

Specify a Fileshare server ID for non-recoverable transient data queues.

Check Require Def. to indicate that a transaction program executing in this region can write to a transient data queue only if it has been defined in the destination control table (DCT). If this option is not checked, when a program attempts to write to a TDQ that has not been defined in the DCT, CICS will create a non-recoverable intra-partition TDQ that has no transaction associated with it. This may result in unexpected program and/or system behaviour if the intention was to write to a pre-defined TDQ of a similar name. We recommend that this option is always checked.

Path (rc)

Specify the path for recoverable temporary storage queues.

Recoverable (recoverable transient data queues)

Check Cold Start to indicate that MSS should reset transient data queues at region startup.

Specify a Fileshare server ID for recoverable transient data queues.

Path (nr)

Specify the path of for non-recoverable temporary storage queues.

Basic Mapping Page Commands

Use Retrieve to specify the character string that BMS control is to interpret as the BMS paging command RETRIEVE.

Use Chain to specify the character string that BMS control is to interpret as the BMS paging command CHAIN

Use Purge to specify the character string that BMS control is to interpret as the BMS paging command PURGE

Use Copy to specify the character string that BMS control is to interpret as the BMS paging command COPY

Single Key

For each key from PF1 through PF24 and PA1 through PA3, specify a character string on the PC that is to equate to a BMS paging command.

Delete

Click this to delete the current SIT. You see this button only if you have editing permissions for the SIT.

Copy

Click this to create a new SIT, based on the entries in the current SIT.

Dump

Click this to create and view dump information for this SIT.

Parent topic: SIT


by StartL

  • DCTs for CICS Startup List name
  • FCTs for CICS Startup List name
  • JCTs for CICS Startup List name
  • PCTs for CICS Startup List name
  • PLTs for CICS Startup List name
  • PPTs for CICS Startup List name
  • Sys62s for CICS Startup List name
  • SysCs for CICS Startup List name
  • Terms for CICS Startup List name
  • TSTs for CICS Startup List name
  • T-Types for CICS Startup List name
  • URIMAPs for CICS Startup List name
  • TCPIPServices for CICS Startup List name
  • XATs for CICS Startup List name
  • DOCTEMPLATEs for CICS Startup List name
  • CICS Defined TRANCLASS
Parent topic: Resources


DCTs for CICS Startup List name

Use this page to view the DCTs defined in resource groups used by the startup list name. You can also create a new resource from this page.

Details

Click this to see detailed information for the DCT resource group in this row.

The rest of the information in this row shows:

  • The name of the DCT.
  • The type of resource (in this case, a DCT).
  • The resource group this DCT belongs to.
  • The short description of the DCT.
New

Click one of the buttons to create a new resource.

Parent topic: by StartL


FCTs for CICS Startup List name

Use this page to view the FCTs defined in resource groups used by the startup list name. You can also create a new resource from this page.

Details

Click this to see detailed information for the FCT.

The rest of the information in this row shows:

  • The name of the FCT.
  • The type of resource (in this case, an FCT).
  • The resource group this FCT belongs to.
  • The short description of the FCT.
New

Click one of the buttons to create a new resource.

Parent topic: by StartL


JCTs for CICS Startup List name

Use this page to view the JCTs defined in resource groups used by the startup list name. You can also create a new resource from this page.

Details

Click this to see detailed information for the JCT in this row.

The rest of the information in this row shows:

  • The name of the JCT.
  • The type of resource (in this case, a JCT).
  • The resource group this JCT belongs to.
  • The short description of the JCT.
New

Click one of the buttons to create a new resource.

Parent topic: by StartL


PCTs for CICS Startup List name

Use this page to view the PCTs defined in resource groups used by the startup list name. You can also create a new resource from this page.

Details

Click this to see detailed information for the PCT in this row.

The rest of the information in this row shows:

  • The name of the PCT.
  • The type of resource (in this case, a PCT).
  • The resource group this PCT belongs to.
  • The short description of the PCT.
New

Click one of the buttons to create a new resource.

Parent topic: by StartL


PLTs for CICS Startup List name

Use this page to view the PLTs defined in resource groups used by the startup list name. You can also create a new resource from this page.

Details

Click this to see detailed information for the PLT in this row.

The rest of the information in this row shows:

  • The name of the PLT.
  • The type of resource (in this case, a PLT).
  • The resource group this PLT belongs to.
  • The short description of the PLT.
New

Click one of the buttons to create a new resource.

Parent topic: by StartL


PPTs for CICS Startup List name

Use this page to view the PPTs defined in resource groups used by the startup list name. You can also create a new resource from this page.

Details

Click this to see detailed information for the PPT in this row.

The rest of the information in this row shows:

  • The name of the PPT.
  • The type of resource (in this case, a PPT).
  • The resource group this PPT belongs to.
  • The short description of the PPT.
New

Click one of the buttons to create a new resource.

Parent topic: by StartL


Sys62s for CICS Startup List name

Use this page to view the Sys62s defined in resource groups used by the startup list name. You can also create a new resource from this page.

Details

Click this to see detailed information for the Sys62 in this row.

The rest of the information in this row shows:

  • The name of the Sys62.
  • The type of resource (in this case, a Sys62).
  • The resource group this Sys62 belongs to.
  • The short description of the Sys62.
New

Click one of the buttons to create a new resource.

Parent topic: by StartL


SysCs for CICS Startup List name

Use this page to view the SysCs defined in resource groups used by the startup list name. You can also create a new resource from this page.

Details

Click this to see detailed information for the SysC in this row.

The rest of the information in this row shows:

  • The name of the SysC.
  • The type of resource (in this case, a SysC).
  • The resource group this SysC belongs to.
  • The short description of the SysC.
New

Click one of the buttons to create a new resource.

Parent topic: by StartL


Terms for CICS Startup List name

Use this page to view the Terms defined in resource groups used by the startup list name. You can also create a new resource from this page.

Details

Click this to see detailed information for the Term in this row.

The rest of the information in this row shows:

  • The name of the Term.
  • The type of resource (in this case, a Term).
  • The resource group this Term belongs to.
  • The short description of the Term.
New

Click one of the buttons to create a new resource.

Parent topic: by StartL


TSTs for CICS Startup List name

Use this page to view the TSTs defined in resource groups used by the startup list name. You can also create a new resource from this page.

Details

Click this to see detailed information for the TST in this row.

The rest of the information in this row shows:

  • The name of the TST.
  • The type of resource (in this case, a TST).
  • The resource group this TST belongs to.
  • The short description of the TST.
New

Click one of the buttons to create a new resource.

Parent topic: by StartL


T-Types for CICS Startup List name

Use this page to view the T-Types defined in resource groups used by the startup list name.

Details

Display detailed information for the T-Type.

The rest of the information in this row shows:

  • The name of the T-Type.
  • The type of resource (in this case, a T-Type).
  • The resource group this T-Type belongs to.
  • The short description of the T-Type.
New

Click one of the buttons to create a new resource.

Parent topic: by StartL


URIMAPs for CICS Startup List name

Use this page to view all defined URIMAPs defined in resource groups used by the startup list name. You can also create a new resource from this page.

Details
Click this to see detailed information for the URIMAP in this row.

The rest of the information in this row shows the name of the URIMAP, the group to which it belongs, whether the URIMAP definition is for an HTTP server or client, and its description.

New
Click one of the buttons to create a new resource.
Parent topic: by StartL


TCPIPServices for CICS Startup List name

Use this page to view all defined TCPIPSERVICEs defined in resource groups used by the startup list name. You can also create a new resource from this page.

Details
Click this to see detailed information for the TCPIPSERVICE in this row.

The rest of the information in this row shows the name of the TCPIPSERVICE, the group to which it belongs and a description of the service.

New
Click one of the buttons to create a new resource.
Parent topic: by StartL


XATs for CICS Startup List name

Use this page to view the XATs defined in resource groups used by the startup list name. You can also create a new resource from this page.

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.
  • The type of resource (in this case, a XAT).
  • The resource group this XAT belongs to.
  • The short description of the XAT.
New

Click one of the buttons to create a new resource.

Parent topic: by StartL


DOCTEMPLATEs for CICS Startup List name

Use this page to view all DOCTEMPLATEs defined in resource groups used by the startup list name.

Details
Click this to display detailed information for the DOCTEMPLATE.

The rest of the information in this row shows the name of the DOCTEMPLATE, the group to which it belongs, and the description of the template.

New
Click one of the buttons to create a new resource.
Parent topic: by StartL


CICS Defined TRANCLASS

Use this page to view the TRANCLASS resources defined in resource groups used by the startup list name. You can also create a new resource from this page.

Details

Click this to see detailed information for the TRANCLASS in this row.

The rest of the information in this row shows:

  • The name of the TRANCLASS.
  • The type of resource (in this case, TRANCLASS).
  • The resource group this TRANCLASS belongs to.
  • The short description of the TRANCLASS.
New

Click one of the buttons to create a new resource.

Parent topic: by StartL


by Type

  • CICS Startup List list_name or CICS Defined resource
  • CICS Defined DCT
  • CICS Defined FCT
  • CICS Defined JCT
  • CICS Defined PCT
  • CICS Defined PLT
  • CICS Defined PPT
  • CICS Defined Sys62
  • CICS Defined SysC
  • CICS Defined Term
  • CICS Defined TST
  • CICS Defined T-Type
  • CICS Defined XAT
  • CICS Defined URIMAP
  • CICS Defined TCPIPSERVICE
  • CICS Defined DOCTEMPLATE
  • CICS Defined TRANCLASS
  • CICS Defined PIPELINE
  • CICS Defined WEBSERVICE
Parent topic: Resources


CICS Defined DCT

Use this page to view all defined DCTs. You can also create a new resource from this page.

Details

Click this to see detailed information for the DCT in this row.

The rest of the information in this row shows:

  • The name of the DCT.
  • The type of resource (in this case, a DCT).
  • The resource group this DCT belongs to.
  • The short description of the DCT.
New

Click one of the buttons to create a new resource.

Parent topic: by Type


CICS Defined FCT

Use this page to view all defined FCTs. You can also create a new resource from this page.

Details

Click this to see detailed information for the FCT.

The rest of the information in this row shows:

  • The name of the FCT.
  • The type of resource (in this case, an FCT).
  • The resource group this FCT belongs to.
  • The short description of the FCT.
New

Click one of the buttons to create a new resource.

Parent topic: by Type


CICS Defined JCT

Use this page to view all defined JCTs. You can also create a new resource from this page.

Details

Click this to see detailed information for the JCT in this row.

The rest of the information in this row shows:

  • The name of the JCT.
  • The type of resource (in this case, a JCT).
  • The resource group this JCT belongs to.
  • The short description of the JCT.
New

Click one of the buttons to create a new resource.

Parent topic: by Type


CICS Defined PCT

Use this page to view all the defined PCTs. You can also create a new resource from this page.

Details

Click this to see detailed information for the PCT in this row.

The rest of the information in this row shows:

  • The name of the PCT.
  • The type of resource (in this case, a PCT).
  • The resource group this PCT belongs to.
  • The short description of the PCT.
New

Click one of the buttons to create a new resource.

Parent topic: by Type


CICS Defined PLT

Use this page to view all the defined PLTs. You can also create a new resource from this page.

Details

Click this to see detailed information for the PLT in this row.

The rest of the information in this row shows:

  • The name of the PLT.
  • The type of resource (in this case, a PLT).
  • The resource group this PLT belongs to.
  • The short description of the PLT.
New

Click one of the buttons to create a new resource.

Parent topic: by Type


CICS Defined PPT

Use this page to view all the PPTs defined on this server. You can also create a new resource from this page.

Details

Click this to see detailed information for the PPT in this row.

The rest of the information in this row shows:

  • The name of the PPT.
  • The type of resource (in this case, a PPT).
  • The resource group this PPT belongs to.
  • The short description of the PPT.
New

Click one of the buttons to create a new resource.

Parent topic: by Type


CICS Defined Sys62

Use this page to view all the Sys62s defined on this server. You can also create a new resource from this page.

Details

Click this to see detailed information for the Sys62 in this row.

The rest of the information in this row shows:

  • The name of the Sys62.
  • The type of resource (in this case, a Sys62).
  • The resource group this Sys62 belongs to.
  • The short description of the Sys62.
New

Click one of the buttons to create a new resource.

Parent topic: by Type


CICS Defined SysC

Use this page to view all the SysCs defined on this server. You can also create a new resource from this page.

Details

Click this to see detailed information for the SysC in this row.

The rest of the information in this row shows:

  • The name of the SysC.
  • The type of resource (in this case, a SysC).
  • The resource group this SysC belongs to.
  • The short description of the SysC.
New

Click one of the buttons to create a new resource.

Parent topic: by Type


CICS Defined Term

Use this page to view all the Terms defined on this server. You can also create a new resource from this page.

Details

Click this to display detailed information for the Term in this row.

The rest of the information in this row shows:

  • The name of the Term.
  • The type of resource (in this case, a Term).
  • The resource group this Term belongs to.
  • The short description of the Term.
New

Click one of the buttons to create a new resource.

Parent topic: by Type


CICS Defined TST

Use this page to view all the TSTs defined on this server. You can also create a new resource from this page.

Details

Click this to see detailed information for the TST in this row.

The rest of the information in this row shows:

  • The name of the TST.
  • The type of resource (in this case, a TST).
  • The resource group this TST belongs to.
  • The short description of the TST.
New

Click one of the buttons to create a new resource.

Parent topic: by Type


CICS Defined T-Type

Use this page to view a list of all the T-Types defined on this server. You can also create a new resource from this page.

Details

Click this to see detailed information for the T-Type in this row.

The rest of the information in this row shows:

  • The name of the T-Type.
  • The type of resource (in this case, a T-Type).
  • The resource group this T-Type belongs to.
  • The short description of the T-Type.
New

Click one of the buttons to create a new resource.

Parent topic: by Type


CICS Defined XAT

Use this page to view all the defined XATs. You can also create a new resource from this page.

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.
  • The type of resource (in this case, a XAT).
  • The resource group this XAT belongs to.
  • The short description of the XAT.
New

Click one of the buttons to create a new resource.

Parent topic: by Type


CICS Defined URIMAP

Use this page to view all defined URIMAPs. You can also create a new resource from this page.

Details
Click this to see detailed information for the URIMAP in this row.

The rest of the information in this row shows the name of the URIMAP, the group to which it belongs, whether the URIMAP definition is for an HTTP server or client, and whether it is enabled or disabled.

New
Click one of the buttons to create a new resource.
Parent topic: by Type


CICS Defined TCPIPSERVICE

Use this page to view all defined TCPIPSERVICE. You can also create a new resource from this page.

Details
Click this to see detailed information for the TCPIPSERVICE in this row.

The rest of the information in this row shows the name of the TCPIPSERVICE and its current status.

New
Click one of the buttons to create a new resource.
Parent topic: by Type


CICS Defined DOCTEMPLATE

Use this page to view the DOCTEMPLATEs available on this server.

Details
Click this to display detailed information for the DOCTEMPLATE.

The rest of the information in this row shows the name of the DOCTEMPLATE and the type of its source.

New
Click one of the buttons to create a new resource.
Parent topic: by Type


CICS Defined TRANCLASS

Use this page to view all defined TRANCLASS resources. You can also create a new resource from this page.

Details

Click this to see detailed information for the TRANCLASS in this row.

The rest of the information in this row shows:

  • The name of the TRANCLASS.
  • The type of resource (in this case, TRANCLASS).
  • The resource group this TRANCLASS belongs to.
  • The short description of the TRANCLASS.
New

Click one of the buttons to create a new resource.

Parent topic: by Type


CICS Defined PIPELINE

Use this page to view all defined PIPELINE resources. You can also create a new resource from this page.

Details

Click this to see detailed information for the PIPELINE in this row.

The rest of the information in this row shows the name of the PIPELINE. The group to which it belongs and its description.

New

Click one of the buttons to create a new resource.

Parent topic: by Type


CICS Defined WEBSERVICE

Use this page to view all defined WEBSERVICE resources. You can also create a new resource from this page.

Details

Click this to see detailed information for the WEBSERVICE in this row.

The rest of the information in this row shows the name of the WEBSERVICE, the group to which it belongs and its description.

New

Click one of the buttons to create a new resource.

Parent topic: by Type


JES

  • Spool
  • Catalog
  • Control
  • Locks
  • Alias
Parent topic: Resources


Spool

  • JES queue type Queue
  • Job job-number
  • Job job-name - ddname
Parent topic: JES


JES queue type Queue

Use this page to view the spool files that have been created as a result of submitting JCL on this server.

Note: The title of the page indicates the type of queue that is currently being displayed, either Input, Held Input , Active, Output, Held Output, or Printed.
Job

Enter a job number in the display field then click this to see details of that job.

Filters

Use this group of fields to apply filters to the list of data sets so that you can just view a subset.

Name filter

Enter the job name of the job for which you want to view the list of data sets in a queue. You can use a single asterisk as a wild card.

User filter

Enter the user ID for which you want to view the list of data sets in a queue. If you did not specify a USER on the JOB card, the user ID is the name of the enterprise server. You can use a single asterisk as a wild card.

Job No filter

Enter the job number of the job for which you want to view the list of data sets in a queue. You can use a single asterisk as a wild card.

Queue

Click one of the buttons to the right of this field to choose a queue to view.

Input

Click this to see the input queue. This lists jobs waiting to start (usually because no initiator for the correct class is currently available).

In Hold

Click this to see the held input queue. This lists jobs that are held (HOLD on the JOB card, or Hold button on a job’s entry in the input queue).

Active

Click this to see the active jobs queue. This lists jobs that are currently running.

Output

Click this to see the output queue. This lists finished jobs whose output is waiting to be sent to an output device (usually because no SYSOUT processor for the correct class is currently available).

Out Hold

Click this to see the held output queue. This lists finished jobs whose output data sets are held (Hold button on a job’s entry in the output queue).

Printing

Click this to see the printing queue. This lists data sets that are currently being printed.

Display

Click this to see details of one of the jobs in the queue. First click the check box to the left of the row describing the job of interest.

Delete

Click this to delete one or more of the jobs in the queue. First click the check boxes to the left of the rows describing the jobs you want to delete. To delete all the jobs click the check box to the left of Display; this selects all the jobs.

Name

Shows the name of the job as specified on the JOB card.

Job No

Shows the number of the job as allocated by JCL Support.

C

Shows the class of the job, as specified on the JOB card.

Pr

Shows the priority of the job, as specified on the JOB card.

User

Shows the user ID under which the job as run. If you did not specify a USER on the JOB card, the user ID is the name of the enterprise server.

Status

Shows the current status of the job. The possible values are

Active | The job is currently being executed
Dispatched | The job is scheduled to a batch or printer process but not yet actioned (transient state)
Input Hold | The job is currently held in the input queue: it will not be executed until you release it
Input Ready | The job is currently in the input queue
Other | The status is unknown
Output Hold | The output from the job is held awaiting release
Output Ready | The output from the job is available to be scheduled
Parsing | MSS is currently parsing the JCL
SYSOUT Disp | The output data set is scheduled to an output device but not yet actioned (transient state)
SYSOUT Hold | The output data set is held awaiting release
SYSOUT Print | The output data set has been printed but other parts of the job are still pending
SYSOUT Ready | The output data set is available to be scheduled to an output device
Submitted

Shows the date and time when the job was submitted.

Parent topic: Spool


Job job-number

Use this page to view details of a job's execution and change control information for a job.

Job

Specify the number of a different job from the one being displayed, then click this to go to the Details page for that job.

Name

Shows the name of the job as specified on the JOB card.

Status

Shows the current status of the job. The possible values are

Active | The job is currently being executed; the Process ID (PID) of the job is shown.
Dispatched | The job is scheduled to a batch or printer process but not yet actioned (transient state)
Input Hold | The job is currently held in the input queue: it will not be executed until you release it
Input Ready | The job is currently in the input queue
Other | The status is unknown
Output Hold | The output from the job is held awaiting release
Output Ready | The output from the job is available to be scheduled
Parsing | MSS is currently parsing the JCL
Hold

Click this to hold the job, so that it cannot run until you click Release. (This button changes to a Release button when you click it.) If you have also changed the value for Class or Priority the change is applied.

Release

Click this to release a held job, so that it can run. (This button changes to a Hold button when you click it.) If you have also changed the value for Class or Priority the change is applied.

Class

Shows the class of the job, as specified on the JOB card. If you want to change the class of the job, specify the new class and click Update. For example, you might want to change the class of a job to a class that has a batch printer SEP defined for it, so that the output data sets can be printed.

Priority

Shows the priority of the job, as specified on the JOB card. If you want to change the priority of the job, specify the new priority and click Update.

Update

Click this to apply any changes you have made to Class or Priority.

User

Shows the user ID under which the job was run. If you did not specify a USER on the JOB card, the user ID is the name of the enterprise server.

Delete

Click this to delete the job from the queue. All the files associated with the DD statements in the job are deleted.

File

Shows the full path of the file containing the JCL that was run.

Messages

The area under Page and File contains all the messages that were output by the JES system during the running of the job, in chronological order.

Reply

Click this to provide a reply to an ACCEPT FROM CONSOLE statement, once you have entered the reply in Enter. You see this only if the job is halted pending a reply.

Enter

Specify your reply to the ACCEPT FROM CONSOLE statement.

SYSOUT

Lists the output files that were created during the running of the job.

Status (output file)

Shows the current status of an output file created by the job:

Active | The job is currently being executed
Complete | The file has been printed
Input Hold | The job is currently held in the input queue: it will not be executed until you release it
Input Ready | The job is currently in the input queue
Other | The status is unknown
Output Hold | The output from the job is held awaiting release
Output Ready | The output from the job is available to be scheduled
Parsing | MSS is currently parsing the JCL
SYSOUT Disp | The output data set is scheduled to an output device but not yet actioned (transient state)
SYSOUT Hold | The output data set is held awaiting release
SYSOUT Printed | The output data set has been printed but other parts of the job are still pending
SYSOUT Ready | The output data set is available to be scheduled to an output device
Class (output file)

Shows the class of the job, as it was when the output files were created.

DDNAME

Shows the name of the data set produced by the job step; the first entry is always for the system log, sys.log.

Step

Shows the name of the job step that produced this file.

Nbr

Shows the number of the job step.

Proc Step

Shows the procedure step, where an output data set was created by a step in a procedure.

Records

Shows the number of records in the output file.

Details

Click this to display details of the output from an individual job step.

Parent topic: Spool


Job job-name - ddname

Use this page to view details of an output file from a job and to change control information for the file.

Job Name
Shows the name of the job to the right of the label. Shows the ddname of the output file to the left of the label.
Status
Shows the current status of the data set. The possible values are
Active | The job is currently being executed
Complete | The file has been printed
Input Hold | The job is currently held in the input queue: it will not be executed until you release it
Input Ready | The job is currently in the input queue
Other | The status is unknown
Output Held | The output from the job is held awaiting release
Output Ready | The output from the job is available to be scheduled
Parsing | MSS is currently parsing the JCL
SYSOUT Disp | The output data set is scheduled to an output device but not yet actioned (transient state)
SYSOUT Print | The output file is currently being printed
SYSOUT Hold | The output data set is scheduled to an output device but not yet actioned (transient state)
SYSOUT Ready | The output data set is available to be scheduled to an output device
Hold
Click this to hold the file, so that its status cannot be changed. (This button changes to a Release button when you click it.) If you have also changed the value for Class or Priority the change is applied.
Release
Click this to release a held file, so that its status can be changed. (This button changes to a Hold button when you click it.) If you have also changed the value for Class or Priority the change is applied.
Class
Shows the class of the file, as specified on the JOB card. If you want to change the class of the file, specify the new class and click Update.
Priority
Shows the priority of the file, as specified on the JOB card. If you want to change the priority of the file, specify the new priority and click Update.
Update
To change the class or priority of a file, modify the appropriate field and then click this.
User
Shows the user ID under which the job was run. If you did not specify a USER on the JOB card, the user ID is the name of the enterprise server.
Records
Shows the number of records in the output file.
Purge

Click this to delete the file.

Step
Shows the name of the job step that produced this file.
Proc Step
Shows the name of the procedure step, where an output data set was created by a step in a procedure.
Step Number
Shows the number of the job step that produced this file.
Proc Step No
Shows the number of the procedure step, where an output data set was created by a step in a procedure.
Codeset

Shows the codeset of the output file.

Created

Shows the date and time the output file was created.

LRECL Min / Max
Shows the maximum and minimum record lengths.
Referenced
Shows the date and time the file was last used in a job.
DS Name
Shows the data set name of the output file, in mainframe format.
PC Name
Shows the filename of the output file, in the format of your local operating system.
Display
Click this to display the contents of the file.
Start
Specify the number of the record where you want the display of the file contents to start. Defaults to 1.
for
Specify how many records you want to be displayed. Clear the field to view all the records in a file. Defaults to 10000. If there were more records than you requested, the final line in the listing warns you that the output was curtailed.
Codeset (for display)
Specify the codeset in which you want the contents to be displayed. Defaults to ASCII.

If you select Both, the system tries to display the contents without regard to the codeset used. For example, the strings x'41424344' and x'a1a2a3a4' are both displayed as "ABCD". You might find this of use if you are not sure what codeset was used to create the file.

The value 'Dump' gives you a hexadecimal dump of the file.

Details
Check this if you want extra details to be included in the display of the file contents.
Job
Specify the number of a different job from the one being displayed, then click this to go to the Details page for that job.
Parent topic: Spool


Catalog

  • Data Catalog (JES)
  • Catalog Entry (JES)
Parent topic: JES


Data Catalog (JES)

Use this page to view the data catalog. This holds information about data sets. No entries display until you click the List button.

List

This is a filter. Enter a string of one or more characters to limit the list of data sets shown to those that begin with the string. For example, enter "ABC*" to view only those data sets that begin with ABC. You can use a single asterisk as a wild card.

Cataloged Only

Choose whether to view just cataloged data sets or uncataloged ones as well as cataloged.

New

Click this to add an entry for a data set to the catalog.

Details

Click this to see details of an individual data set.

Delete

Click entries in the catalog list then click this button to delete the selected entries.

DS Org

Shows the data set organization of the data set. Can be one of:

DA | Direct access
GDG | Generation data group
IS | Indexed sequential
PDSM | Partitioned data set member (Micro Focus organization)
PO | Partitioned
PS | Physical sequential
VSAM | Virtual storage access method

When selecting VSAM in the DS Org field, a ShareOptions section appears. A list box allows you to set the following:

  • Cross Region: Valid values are 0, 1, 2, 3 or 4. A value of 0 (zero) means that SHAREOPTIONS are not applied to the DSN. See SHAREOPTIONS for a description of the other values.
  • Cross System: Valid values are 0, 3 or 4. Any value set for Cross System is read and stored in the catalog and in the data file, which can be included when sending a job step to the mainframe for processing.
DS Name

Shows the data set name of the output file, in mainframe format.

DCB

Click to see the details of an individual data set. The same as selecting a data set and clicking the Details button.

Parent topic: Catalog


Catalog Entry (JES)

Use this page to add an entry to the catalog or to view and change information for a cataloged data set.

Apply

Click this to apply your changes to the entry in the catalog.

Copy

Click this to copy a catalog entry.

Delete

Click this to delete the data set from the disk.

DS Name

If you are adding an entry, specify the data set name of the file, in mainframe format. If you are viewing an entry, shows the data set name of the file, in mainframe format.

Catalog

Check this if you want the file to be included in the catalog.

Physical File

If you are adding an entry, specify the filename of the physical file held on your machine, in the format of your local operating system. If you are viewing an entry, shows the filename of the file, in the format of your local operating system.

DSOrg

Shows the data set organization of the data set. Can be one of:

DA | Direct access
GDG | Generation data group
IS | Indexed sequential
PDSM | Partitioned data set member (Micro Focus organization)
PO | Partitioned
PS | Physical sequential
VSAM | Virtual storage access method

When selecting VSAM in the DS Org field, a ShareOptions section appears. A list box allows you to set the following:

  • Cross Region: Valid values are 0, 1, 2, 3 or 4. A value of 0 (zero) means that SHAREOPTIONS are not applied to the DSN. See SHAREOPTIONS for a description of the other values.
  • Cross System: Valid values are 0, 3 or 4. Any value set for Cross System is read and stored in the catalog and in the data file, which can be included when sending a job step to the mainframe for processing.
RECFM

Shows the record format of the data set. For all data set organizations except VSAM can be one of:

F | Fixed
FA | Fixed
FB | Fixed blocked
FBA | Fixed blocked
FBM | Fixed blocked
FBS | Fixed blocked, spanned
FM | Fixed
FS | Fixed spanned
LSEQ | Line sequential
U | Undefined
V | Variable
VA | Variable
VB | Variable blocked
VBA | Variable blocked
VBM | Variable blocked
VBS | Variable blocked, spanned
VM | Variable
VS | Variable, spanned

For VSAM data set organization can be one of:

ES | Entry sequence
KS | Key sequence
LS | Linear sequence
RR | Relative record
Codeset

Specify the codeset in which you want the contents to be stored. Defaults to ASCII.

Created

Shows the date and time the file was created.

LRECL

Specify the record length for fixed-length records, or the maximum record length for variable-length records, including the 4-byte record header.

Referenced

Shows the date and time the file was last used in a job.

BLKSIZE
Specify the length of a block in bytes.
Display

Click this to display the contents of the file.

Start

Specify the number of the record where you want the display of the file contents to start. Defaults to 1.

for

Specify how many records you want to be displayed. Clear the for field to view all the records in a file. Defaults to 10000. If there were more records than you requested, the final line in the listing warns you that the output was curtailed.

Attention: If you ask for all the records to be displayed in a very large file, your browser will take some time to display all the records, and might run out of memory.
Codeset (for display)

Choose the codeset in which you want the contents to be displayed. Defaults to ASCII.

If you select Both, the system tries to display the contents without regard to the codeset used. For example, the strings x'41424344' and x'a1a2a3a4' are both displayed as "ABCD". You might find this of use if you are not sure what codeset was used to create the file.

The value 'Dump' gives you a hexadecimal dump of the file.

Details

Check this if you want extra details to be included in the display of the file contents.

Parent topic: Catalog


Control

  • JCL Control
Parent topic: JES


JCL Control

Use this page to submit JCL jobs and start batch initiator and batch printer SEPs for this server.

Reply

Click this to provide a reply to an ACCEPT FROM CONSOLE statement. You see this only if the job is halted pending a reply.

PID

Shows the Process ID of the job waiting for the reply.

Description

Shows the job number of the job waiting for the reply and the reason why the reply is required.

Please enter a JCL file name (local to this ES).

Specify the path and name of the file containing the JCL job that you want to run.

Submit

Click this to run the JCL job you have specified.

Browse

Click this to search for the JCL file on your file system.

VSE

Click this if the job uses VSE JCL.

JES2

Click this if the job uses JES2 JCL.

JES3

Click this if the job uses JES3 JCL.

Start

Click this to start a batch initiator SEP or a batch printer SEP dynamically - it is created and starts at once, and exists only until the enterprise server is stopped. Specify details of the SEP in other fields on this page first.

Classes

Specify the classes that you want the batch initiator SEP or a batch printer SEP you are about to start to support.

Type

Choose the type of SEP you want to start from the list.

Exit Module

Specify the name of a printer exit module that you want to be invoked when the batch printer SEP is printing a file. Specify this only if you chose Printer in Type.

Debug

Click this if you want to debug the JCL job that will run in this SEP.

Printer Name

Select the printer that you want files output by this batch printer SEP to be sent to. Only printers known to the operating system are shown.

Job

Enter a job number in the entry field then click this to see details of that job.

Parent topic: Control


Locks

  • Locks (Active)
Parent topic: JES


Alias

  • Alias Table
Parent topic: JES


Alias Table

Lists the Micro Focus implementations of well-known mainframe utilities. If you have sufficient access rights, you can add or delete entries, or change an entry so that your own utility is used. See Resource Classes for ESMAC and Operator Command Security for details on configuring access rights for the Alias table.

The use of this table means that mainframe JCL that references any of these mainframe utilities does not need to be changed to run in Enterprise Server.

Program Name
The name of the mainframe utility.
Alias
The Micro Focus implementation of the utility.
Parent topic: Alias
Related reference
HHSACHESSA33.html


IMS

  • IMS Transactions
  • Create, View and Edit an IMS Transaction
  • IMS Control
Parent topic: Resources


IMS Transactions

Use this page to view the IMS transactions defined on the current server.

New

Click this to define a new transaction for use on the current server.

Details

Click this to view detailed information for the transaction. The rest of this row shows the following information for a transaction:

  • Name.
  • PSB name.
  • Description.
Parent topic: IMS


Create, View and Edit an IMS Transaction

Use this page to define a new transaction or view an existing one.

Name

Specify the name of the transaction.

Description

Specify a description for the transaction.

PSB Name

Specify the name of the PSB associated with this transaction.

Class

Specify the message class for this transaction.

Program Name

Specify the name of the application program associated with this transaction.

Schedule

Choose whether the application program can be scheduled into more than one message processing region simulatneously:

  • Parallel - the application program can be scheduled into more than one message processing region simulatneously.
  • Serial - the application program cannot be scheduled into more than one message processing region simulatneously.
SPA Size

Specify the size of the conversational scratchpad area (SPA). The size specified must be between 16 bytes and 32767 bytes.

SPA Truncate

Choose the setting of the truncated data option:

  • unspecified - the data option currently in effect for the conversation is used.
  • STRUNC - truncated data option is on.
  • RTRUNC - truncated data option is off.
Wait for input

Check this to specify that this is a wait-for-input (WFI) transaction.

Transaction threshold

Specify the maximum length of time in seconds that a transaction can run before a message is logged to the console to indicate that it has exceeded its threshold. This must be in the range 0 through 65535. A value of 0 indicates that there is no threshold.

Check Use System Value to use the system wide value for the transaction time threshold set in the ESMAC IMS Control page.

Priority

Specify the priority assigned to this transaction (and any messages it creates) when the number of input transactions enqueued and waiting to be processed is less than the value specified in P-Limit Count. The priority must be in the range 0 through 14. The default is 1.

Priority Limit

Specify the priority assigned to this transaction (and any messages it creates) when the number of input transactions enqueued and waiting to be processed is greater than or equal to the value specified in P-Limit Count. The priority must be in the range 0 through 14. The default is 1.

Max Segments

Specify the maximum number of application program output segments that are allowed into the message queues for each Get Unique (GU) call from the application program. The number must be in the range 0 through 65535. The default is 0. Specifying 0 indicates that the number of segments is not checked at execution time.

P-Limit Count

Specify the number of input transactions enqueued and waiting to be processed that determines whether the transaction's priority is the value specified in Priority or Priority Limit. The count must be in the range 1 through 65535. The default is 65535.

Deadlock Timeout

Specify the maximum time in seconds that the message processing region will permit this transaction to wait for a resource that has been locked by another process. A value of 0 indicates that there is no timeout.

P-Limit Time

Specify how many seconds a program can spend processing this transaction (or a message from it) in a single scheduling. The number must be in the range 1 through 65535. The default is 65535. Specifying 65535 indicates that no limit is to be imposed.

Status

Choose the status of the transaction program:

  • Enabled - the transaction program is enabled.
  • Disabled - the transaction program is disabled.
Process Limit

Specify how many of this transaction's messages a program can process in a single scheduling. This must be in the range 1 through 9999. The default is 9999. Specifying 9999 indicates that no limit is to be imposed.

Edit

Choose whether or not input data is to be translated to uppercase:

  • ULC - input data is not to be translated to uppercase.
  • UC - input data is to be translated to uppercase.
Edit Exit

This feature is currently not supported.

Fast Path

Specify the the size of the EMH buffer required to run the transaction using Fast Path processing. The minimum value is 12 and the maximum is 30720. Specifying 0 indicates that the transaction cannot be run using Fast Path processing.

In Doubt

Choose what happens if a transaction program using intersystem communication abends at a critical moment during syncpoint or abend processing:

  • Backout - the effects of the transaction are backed out using ROLLBACK.
  • Commit - any changes are committed.
  • Wait - critical resources are locked until the session has recovered, and are then backed out or committed in step with the remote system.
Response Mode

Check this to specify that, for terminals with a default of OPTIONS=TRANRESP, no additional messages are to be allowed after this transaction is entered until this transaction sends a response message back to the terminal. Leave this option unchecked to specify that input should not stop after this transaction is entered.

Tracing

Choose the type of tracing to be performed for the transaction:

  • Standard - tracing is performed.
  • Special - special tracing is performed.
  • No - no tracing is performed.
Codeset

Choose the codeset to use for this transaction:

  • Default - The transaction inherits the system bias codeset.
  • ASCII - The transaction uses ASCII.
  • EBCDIC - The transaction uses EBCDIC.
Dump On ABEND

Check this to request a program dump if the transaction program abends.

MFS Attributes

Choose how attributes are defined in the transaction program:

  • Default - The program defines attributes as defined by the system bias value (which is binary, by default).
  • Binary - The program defines attributes as binary values, for example:
    05 ATTRIBUTE-VARIABLES.
   10 CURSOR-ATTR    PIC X(2) VALUE X"C0C1".
   10 ERROR-ATTR     PIC X(2) VALUE X"C0C9".
   10 OK-ATTR        PIC X(2) VALUE X"00C1".
   10 PROT-ATTR      PIC X(2) VALUE X"00F1".
  • Character - The program defines attributes as characters, for example:
    05 ATTRIBUTE-VARIABLES.
   10 CURSOR-ATTR PIC X(2) VALUE "{A".
   10 ERROR-ATTR PIC X(2) VALUE "{I".
   10 OK-ATTR PIC X(2) VALUE " A".
   10 PROT-ATTR PIC X(2) VALUE " 1".

    This setting only has an effect if the program is compiled using the ASCII character set; it is ignored if the program is compiled using EBCDIC.

MFS Null

Specify the character to use as the NULL. You can enter the value in character form or hexadecimal form (X'nn'). The default is X'1A'.

This setting only has an effect if the program is compiled using the ASCII character set; it is ignored if the program is compiled using EBCDIC.

Security Keys
all
Choose a setting to apply to all the security keys:
  • On - enables all the security keys
  • Off - disables all the security keys
1-64

Check any of the boxes 1 through 24 to activate that security key.

Active, Install

Click this to install (make active) this resource.

Delete

Click this to delete this transaction. You see this button only if you have permission to edit the transaction.

Copy

Click this to create a new transaction. The values on the current page will be used as the basis for the values in the new transaction.

Dump

Click this to create and view display a dump of the transaction information.

Parent topic: IMS
Parent topic: Pages for Creating Resources
Related tasks
To define a transaction manually


IMS Control

Use this page to start message processing regions (MPRs) and perform a number of other IMS-related administration functions for this server.

Commands
/dis TRAN all

Click this to execute a /dis TRAN all command. The results are displayed below the entry field.

/dis USER all

Click this to execute a /dis USER all command. The results are displayed below the entry field.

/dis DB all

Click this to execute a /dis DB all command. The results are displayed below the entry field.

/dump TM

Click this to execute a /dump TM command. The results are displayed below the entry field.

Enter

Click this to execute the command specified in the entry field to the right. The results are displayed below the entry field.

Start IMS MPRs (Message Processing Regions)
Start
Click this to start a message processing region.
MPR Classes

Specify the transaction classes that can run in the message processing region.

Debug

Click this if you want to debug the IMS transactions that will run in this message processing region.

Renew MFS Formats and IMS ACBs
Renew
Click this to delete information from the system cache and to reload the current information from disk.
MFS Formats
Select this to delete information on MFS format blocks.
ACBs
Select this to delete information on application control blocks

TM System Overview and Control
Message Queue Max
The number of blocks representing the maximum size to which the IMS message queue data store can expand. The value must be in the range of 4 through 63488.
Cushion
The size of the cushion to be reserved for graceful lack-of-space behavior is represented as a percentage of the maximum message queue size from 0% to 7.97%. The default is 4%.
Transaction Threshold
Specify the maximum length of time in seconds that a transaction can run before a message is logged to the console to indicate that it has exceeded its threshold. This must be in the range 0 through 65535. A value of 0 indicates that there is no threshold.
Q Flush Aggregate
on
Enables the aggregation of transactional flushing of operating system buffers to disk.
ms
An interval of time, in milliseconds, during which flush requests are held and allowed to accumulate before flushing. Valid values are 0 through 255.
Flush disable
Disables dynamic flushing, meaning that the TM system unilaterally flushes operating system buffers to your physical disk only at each keypoint.
Keypoint Frequency
Specify how many thread requests are to be processed before a keypoint is generated. This must be in the range 0 through 65535. The default is 64. Specifying 0 indicates that keypoints are only generated when the enterprise server starts and shuts down.
TM Message Queue Diagnostics
Display summary overview of IMS Message Queues
Click this to view the content of the IMS message queue.
Display block-number/segment of message queue

Click this to view a specified segment of the IMS message queue.

Parent topic: IMS
Related concepts
Configuring the IMS Message Queue
Dynamic IMS Message Queue Expansion
Dynamic IMS Message Queue Performance Tuning
Related tasks
To enable dynamic IMS message queue performance tuning
To dynamically tune IMS message queue performance
To dynamically adjust the IMS message queue configuration
Related reference
Server Instance Properties: MSS IMS TM General


Pages for Creating Resources

  • CICS DCT
  • CICS FCT
  • CICS JCT
  • CICS PCT
  • CICS PLT
  • CICS PPT
  • CICS Sys62
  • CICS SysC
  • CICS T-Type
  • CICS Term
  • CICS TST
  • CICS URIMAP
  • CICS TCPIPSERVICE
  • CICS XAT
  • CICS DOCTEMPLATE
  • Create, View and Edit an IMS Transaction
  • CICS TRANCLASS
  • CICS PIPELINE
  • CICS WEBSERVICE
Parent topic: Resources


CICS DCT

Use this page to create a new DCT. A DCT is a definition of a transient data queue.

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new DCT.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Group List

Click this to display the CICS Group group_name.

Add

Click this to save changes you have made to the page, refresh the page and add the new DCT to the group you specify in Grp. The button changes to Apply.

Name

Specify a name for the DCT (can be up to 60 characters).

Grp

Choose a group to which this DCT will belong. The list of groups from which you can choose include only those which can be edited by you.

Description

Specify a description for the DCT (can be up to 60 characters).

Type

Choose the destination for transient data:

  • Intra-Part - intrapartition
  • Indirect - indirect
  • Extra-Part - extrapartition
  • Internal Rdr - the internal reader to which CICS applications can direct a JCL jobstream for execution by the JCL engine
Indirect Name

Specify the symbolic name of the indirect destination. The symbolic name is used when writing to the destination. The name can be one to four characters in length. This control has an effect only if you selected Indirect in the Type control.

Recoverable

Check this to enable recovery of the destination in the event of an abnormal termination of either MSS or the transaction processing the destination. This control only has an effect if you selected Intra in the Type control.

Name (Remote Queue)

Specify the name of a remote transient data destination.

SYSID

Specify the system or region in which the remote transient data destination resides. The name specified must be the same as that given in Name in the SysC or Sys62 definition.

Transaction

Specify the name of the transaction that is to be automatically initiated when the trigger level specified in Trigger Level is reached. If no transaction is specified, or Trigger Level is set to 0, some other means must be used to schedule transactions to read records from the destinations.

Terminal

Specify the terminal associated with the transient data destination. The terminal must be defined to MSS.

Trigger Level

Specify the number of records to be accumulated before a task is automatically initiated to process them. The maximum number you can enter is 32767.

File Name

Specify the filename of the extrapartition file.

File Path

Specify the pathname of the extrapartition file.

Extension

Specify the filename extension of the extrapartion file.

Fileshare

Specify the name of the stand-alone Fileshare server that controls this file (if required).

Record Max

Specify the maximum length of a record in the extrapartition file.

Record Min

Specify the minimum length of a record in the extrapartition file.

Initial State

Choose the initial status of the data set:

  • Open - the data set is opened by system initialization.
  • Closed - the data set remains closed until you indicate that you want to open it.
Type (Extra-partition File Characteristics)

Choose whether the file is line sequential:

  • Normal - The file is not line sequential.
  • Line Sequential - The file is line sequential.
Print Attributes

Choose whether or not a forms control character is contained in the first position of each record:

  • No Control - Records have no forms control character.
  • ASA - Records contain a form control character that is in ASA format.
  • Machine - Records contain a form control character that is in machine format.
I/O Type

Choose the type of input/output:

  • Input - Input data.
  • Output - Output data.
  • Read Backwards - Input data read from the end of the dataset to the beginning.
Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - enables all the resource keys.
  • Off - disables all the resource keys.
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Active, Display

Click this to display the currently installed definition of this resource.

Active, Install

Click this to install (make active) this resource.

Delete

Click this to delete this DCT. This button is displayed only after you click Add.

Copy

Click this to create a new DCT, using the values set on this page as the basis for the new DCT. This button is displayed only after you click Add.

Dump

Click this to create and view dump information for this DCT. This button is displayed only after you click Add.

Parent topic: Pages for Creating Resources


CICS FCT

Use this page to create a new FCT.

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new FCT.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Group List

Click this to display the CICS Group group_name page.

Add

Click this to save changes you have made to the page, refresh the page and add the new FCT to the group you specify in Grp. The button changes to Apply.

Name

Specify a name for this FCT.

Grp

Choose a group to which this FCT will belong. The list of groups from which you can choose include only those which can be edited by you.

Description

Specify a description of the file (can be up to 60 characters).

Type

Choose the file type:

  • KSDS - key sequence data set
  • ESDS - entry sequence data set
  • RRDS - relative record data set
  • Alt Index - alternate index
  • Undefined - remote file (Specify the System ID on the Remote page)

You must uncheck Use Catalog before you can specify a file type. This is because if you use the catalog this information is stored there, not in the FCT entry.

Format

Choose the format for the file. You must uncheck Use Catalog before you can choose a file format. This is because if you use the catalog this information is stored there, not in the FCT entry.

LRECL Min

Specify the minimum logical record length of the file, in bytes, in the range 1 through 32767. This must not be greater than the value of Max LRECL.

For fixed length records, set this value equal to Max LRECL.

You must uncheck Use catalog before you can specify a minimum logical record length. This is because if you use the catalog this information is stored there, not in the FCT entry.

LRECL Max

Specify the maximum logical record length of the file, in bytes in the range 1 through 32767. This must not be less than the value of Min LRECL.

For fixed length records, set this value equal to Min LRECL.

Key Position

For files of type KSDS or ALT specify the byte number at which the record key begins in the range 1 through 32767. Bytes are numbered from 1.

Key Length

For files of type KSDS or ALT, specify the length of the record key in bytes (within the range 1 through 32767). The value "Key position+Key length-1" must not be greater than Min LRECL.

For files of type Undefined, specify the length of the record key, which must not be greater than Max LRECL.

Use Catalog

Check this if you want to use the catalog to store information about the file. If you check this, certain parameters on this page become irrelevant; the description for each parameter indicates whether Use Catalog affects that parameter.

Base Name

Specify the base filename for an alternate index. CICS references alternate indexes by a user-assigned name. This connects the alternate index definition to the base file.

Dataset Name

Specify the data set name for this file as used on the mainframe. You must check Use Catalog before you can specify a data set name. This is because the catalog uses this information.

Status

Choose whether the file is accessible to transactions at system startup

  • Enable - the file is accessible to transactions at system startup.
  • Disable - the file is not accessible to transactions at system startup. A disabled file returns the reference "DISABLED". This can cause problems for some applications; if this is true for your application, set Unenable instead.
  • Unenable - the file is not accessible to transactions at system startup. An unenabled file returns a reference "NOTOPEN", which can be handled by those applications that cannot handle a "DISABLED" reference.

The value set by this control is ignored if the file resides on a remote system.

Access

Check one or more boxes to set the read/write permissions for the file. You can check:

  • Read - enables applications to read records from the file.
  • Add - enables applications to add records to the file.
  • Browse - enables applications to browse the file.
  • Delete - enables applications to delete records from the file.
  • Update - enables applications to update records in the file.
  • Exclusive - CICS Exclusive Control. Enables application to gain exclusive control of a record within a file.
Set

Check one or more boxes to set various file parameters. You can select the following options:

  • Start Open - check this to indicate that the file is to be opened at system startup. If you want the file to be opened at system startup and accessible to transactions, you must also select Enabled in the Status select box.
  • Start Empty - check this to indicate that the current contents of the file are to be deleted at system startup.
  • Backward Recovery - check this to indicate that the file is a protected resource changes to which can be backed out. The file must be accessed through a Fileshare server.
  • Forward Recovery - check this to indicate that journals are to be used to record changes to the file to enable forward recovery. The file must be accessed through a Fileshare server.
  • Allow Duplicate Keys - check this if the file can have duplicate keys. The file must be an alternate index (Type set to Alt index) and you must have unchecked Use Catalog, because if you use the catalog this information is stored there, not in the FCT entry.
  • EBCDIC Collating Sequence - check this to indicate that the EBCDIC collating sequence is to be used for this file. You must uncheck Use Catalog before you can check this, because if you use the catalog this information is stored there, not in the FCT entry.
Remote SYSID

Specify the system ID of the remote system on which the file resides. The name specified must be the same as that given in Name in the SysC or Sys62 definition.

You must uncheck Use Catalog before you can specify a system ID for the remote system. This is because the catalog is used only for storing information about files held locally.

Remote File

Specify the name of the file on the remote system. You must uncheck Use Catalog before you can specify a name for a remote file. This is because the catalog is used only for storing information about files held locally.

Override File Name

Specify the filename of the physical file if you want to override the default. Do not include the file extension. Can be up to 255 characters.

If you do not specify this entry, the physical file name defaults to the name of the FCT entry.

You cannot use this default if you specify a Fileshare server; you must specify a physical file name.

You must uncheck Use Catalog before you can specify a filename. This is because if you use the catalog this information is stored there, not in the FCT entry.

File Extension

Specify the file extension of the physical file if you want to override the default. Can be up to 3 characters. You must uncheck Use Catalog before you can specify an extension. This is because if you use the catalog this information is not required.

File Path

Specify the path of the physical file if you want to override the default. Do not include the filename or file extension. Can be up to 255 characters. You must uncheck Use catalog before you can specify a path. This is because if you use the catalog this information is stored there, not in the FCT entry.

Fileshare Server

Specify the ID of the Fileshare server on which the file resides. Can be up to 16 characters. You must uncheck Use Catalog before you can specify a Fileshare server. This is because if you use the catalog this information is stored there, not in the FCT entry.

Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - enables all the resource keys.
  • Off - disables all the resource keys.
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Active, Display

Check this to display the currently installed definition of this resource.

Active, Install

Check this to install (make active) this resource.

Delete

Check this to delete this FCT. This button is displayed only after you click Add.

Copy

Check this to create a new FCT, using the values set on this page as the basis for the new FCT. This button is displayed only after you click Add.

Dump

Check this to create and view dump information for this FCT. This button is displayed only after you click Add.

Parent topic: Pages for Creating Resources


CICS JCT

Use this page to create a new JCT (journal control table).

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new JCT.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Group List

Display the CICS Group group_name page.

Add

Click this to save changes you have made to the page, refresh the page and add the new JCT to the group you specify in Grp. The button changes to Apply.

Name

Specify a name for this JCT.

Grp

Choose a group to which this JCT will belong. The list of groups from which you can choose include only those which can be edited by you.

Description

Specify a description for the JCT (can be up to 60 characters).

Type

Choose the type of journal:

  • Disk 1 - A journal on disk that has one data set to be reused when full.
  • Disk 2 - A journal on disk that has two data sets to be used alternately. You must specify this to minimize operator involvement during a takeover.
  • Disk 2 Pause - A journal on disk that has two data sets to be used alternately. When the second data set is full, the system is paused to enable the operator to copy the data sets to another location before resuming with the first data set.
  • SMF - Mainframe System Management Facility format
  • Tape 1 - A journal on one tape drive.
  • Tape 2 - A journal on two tape drives.
File Name

Specify the filename of the journal.

File Path

Specify the pathname of the journal file.

Extension

Specify the filename extension of the journal file.

Fileshare

Specify the name of the Fileshare server that controls this data set.

Record Max

Specify the maximum length of a record in the journal file.

Record Min

Specify the minimum length of a record in the journal file.

Initial State

Choose the initial status of the journal:

  • New - a new journal data set is created at system initialization.
  • Append - data is appended to an existing journal data set.
Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - enables all the resource keys
  • Off - disables all the resource keys
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Delete

Click this to delete this JCT. This button is displayed only after you click Add.

Copy

Click this to create a new JCT, using the values set on this page as the basis for the new JCT. This button is displayed only after you click Add.

Dump

Click this to create and view dump information for this JCT. This button is displayed only after you click Add.

Parent topic: Pages for Creating Resources


CICS PCT

Use this page to create a new PCT.

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new PCT.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Group List

Click this to display the CICS Group page group_name.

Add

Click this to save changes you have made to the page, refresh the page and add the new PCT to the group you specify in Grp.

Name

Specify a name for this PCT.

Grp

Choose a group to which this PCT will belong. The list of groups from which you can choose includes only those which can be edited by you.

Description

Specify a description of the transaction program (can be up to 60 characters).

Program Name

For local programs only, specify the name of the application program to be run when this transaction is invoked. Leave this field blank if you enter a value in the remote system ID field.

Can be up to eight characters (A-Z, 0-9, #, @, or $). The name is translated to upper case.

Work Area

Specify the size of the transaction program's Transaction Working Area (TWA) in bytes, in the range 0 through 32767.

Remote SysID

Specify the system ID of the remote system. The name specified must be the same as that given in Name in the SysC or Sys62 definition.

Remote PCT

Specify the transaction ID of the transaction program on the remote system. You must specify Remote SysID before you can specify a transaction ID.

Can be up to four alphanumeric characters, the first of which must be a letter. Do not use the letter C as the first character; transaction IDs beginning with C are reserved for use by MSS.

Status

Choose a status for the transaction program:

  • Enabled - the transaction program is enabled.
  • Disabled - the transaction program is disabled.
In Doubt

Choose what is to happen if a transaction program using intersystem communication abends at a critical moment during syncpoint or abend processing:

  • Backout - the effects of the transaction are backed out using ROLLBACK. To use this option, files used by the transaction program must have Backward recovery checked on the FCT page.
  • Commit - any changes are committed.
  • Wait - critical resources are locked until the session has recovered, and are then backed out or committed in step with the remote system.
Upper Case

Check this if you want the transaction program to translate input into upper case

Tracing

Choose the type of tracing to be performed for the transaction program:

  • None - No tracing is performed.
  • Normal - Tracing is performed.
  • Special - Special tracing is performed.
Dynamic Route

Check this to have the program status (local or remote) determined dynamically at user invocation time. If this is unchecked, the program status is made local or remote according to the value of System ID.

Security

Use these check boxes to control the way in which resource authorization checks are performed. If they are not checked, the only check performed will be to confirm that the user has authority to run the transaction. If you check RLS (Resource Level Security), Enterprise Server will check the user's authorization for all resources that the transaction accesses (e.g. file access, TDQ, TSQ, LINK, DPL, START and so on). Checking CMD(for Command) will check the authorization on all the EXEC CICS command operations (e.g. EXEC CICS SET/ENABLE/DISABLE).

Note that IBM Category 3 Transactions do not have security checking at all, so the transactions are allowed for everyone with no authorization calls.

Priority

Specify the transaction priority of the transaction program in the range 0 through 255, where 255 is the highest priority.

The priority of a transaction is the sum of:

  • The terminal priority
  • The transaction priority (this field)
  • The operator priority

This sum must not be greater than 255.

Dump on ABEND

Check this to create a program dump if the transaction program abends.

3270 Screen

Specify the screen size to be used by the transaction program. Select:

  • Default to use the default screen size (as defined in the Typeterm entry).
  • Alternate to use the alternate screen size (as defined in the Typeterm entry).
Inbound

Check this to indicate that this transaction can be initiated by an inbound user action.

Input Timeout

Specify the maximum time in seconds allowed for operator response to an explicit CICS RECEIVE, WEB OPEN, WEB SEND, WEB RECEIVE, or WEB CONVERSE command before this transaction is abended. A value of 0 indicates that there is no timeout, and the system will wait indefinitely for a response.

Check Use System Value to use the system wide value for Input Timeout (as shown on the ESMAC Control screen) rather than the PCT entry.

Runaway Timeout

Specify the maximum continuous period of time in seconds that the region will allow this transaction to run without making a CICS, EZASOKET or WebSphere MQ API call. When this time is exceeded, the transaction is abended. A value of 0 indicates that there is no timeout.

Check Use System Value to use the system wide value for Runaway Timeout (as shown on the ESMAC Control screen) rather than the PCT entry.

Deadlock Timeout

Specify the maximum time in seconds that the region will permit this transaction to wait for a resource that has been locked by another process. A value of 0 indicates that there is no timeout.

Check Use System Value to use the system wide value for Deadlock Timeout (as shown on the ESMAC Control screen) rather than the PCT entry.

Transaction Threshold

Specify the maximum length of time in seconds that a transaction can run before a message is logged to the console to indicate that it has exceeded its threshold. A value of 0 indicates that there is no threshold.

Check Use System Value to use the system wide value for the transaction time threshold (as shown on the ESMAC Control screen) rather than the PCT entry.

Resource Keys, all

Choose a setting to apply to the resource keys:

  • On - enables all the resource keys.
  • Off - disables all the resource keys.

Check any of the boxes 1 through 24 to activate that resource key.

Security Keys, all

Choose a setting to apply to the security keys:

  • On - enables all the security keys.
  • Off - disables all the security keys.

Check any of the boxes 1 through 64 to activate that security key.

Active

Click Display to display the currently installed definition of this resource.

Click Install to install (make active) this resource.

Delete

Click this to delete this PCT. This button is displayed only after you click Add.

Copy

Click this to create a new PCT, using the values set on this page as the basis for the new PCT. This button is displayed only after you click Add.

Dump

Click this to create and view dump information for this PCT. This button is displayed only after you click Add.

Parent topic: Pages for Creating Resources


CICS PLT

Use this page to create a new PLT.

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new PLT.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Group List

Click this to display the CICS Group page group_name.

Add

Click this to save changes you have made to the page, refresh the page and add the new PLT to the group you specify in Grp. When you click Add, the button changes to Apply.

Name

Specify a name for the PLT.

Grp

Choose a group to which this PLT will belong. The list of groups from which you can choose include only those that can be edited by you.

Description

Specify a description of the transaction program (can be up to 60 characters).

01 - nn

A numbered list of programs.

If you are creating a PLT, you see one empty field numbered 01. Enter a program to be used by this PLT. Click Add. The startup list is saved. If there are no errors, the page is refreshed, a new empty field (labeled 02) is added to the page, and the Add button changes to Apply. Each time you add a resource group, click Apply.

If you are creating a PLT based on an existing PLT, you will see as many fields are there were programs specified in the PLT from which you created this PLT. Note that, if you can edit the PLT, there is always a blank field added at the end of the list.

You can change the order of the programs in the PLT. Use Down arrow button to move a program down the list. Use Up arrow button to move a program up the list.

Delete an entry in the PLT by clicking Delete button.

Run once/Run in each process

Click Run once to specify that the program should only run once, when the PLT is first initiated. Click Run in each process to specify that the program should run every time the PLT is initiated.

Delete

Click this to delete this PLT. This button is displayed only after you click Add.

Copy

Click this to create a new PLT, using the values set on this page as the basis for the new PLT. This button is displayed only after you click Add.

Dump

Click this to create and view dump information for this PLT. This button is displayed only after you click Add.

Parent topic: Pages for Creating Resources


CICS PPT

Use this page to create a new PPT.

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new PPT.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Group List

Click this to display the CICS Group page group_name.

Add

Click this to save changes you have made to the page, refresh the page and add the new PPT to the group you specify in Grp.

Name

Specify a name for this PPT.

Grp

Choose a group to which this PPT will belong. The list of groups from which you can choose includes only those that can be edited by you.

Description

Specify a description of the transaction program (can be up to 60 characters).

Status

Choose a status for the program:

  • Enabled - enables this program to be used in a normal manner.
  • Disabled - prevents the program from being used until specifically enabled using master terminal services.
Type

Choose a type for the resource:

  • Program - this resource is a program.
  • Data Area - this resource is a data table.
Resident

Check this if you want to enable this program to reside in the application server's program cache after it has been loaded.

Commarea

Specify the amount of storage to be allocated to the communications area (COMMAREA) to enable MSS to behave like mainframe CICS. The size is in the range 0 through 32767. The effect of this is that when a program is passed a COMMAREA smaller than the COMMAREA defined in the program, the passed COMMAREA is automatically extended in length to fill the defined space.

Language

Choose the language the program is written in.

Save, Working Storage

Check this to have load requests ignored if the program is already in storage.

Uncheck this to have a fresh copy of the program loaded every time a load request for the program is issued.

Remote SysID

If the program resides in a remote region, specify the 4-character, remote system identifier. The name specified must be the same as that given in Name in the SysC or Sys62 definition.

If the program resides in the local region, leave this field blank.

Rmt Trans ID

Specify the transaction ID of the transaction program on the remote system. You must specify System ID before you can specify a transaction ID.

Can be up to four alphanumeric characters, the first of which must be a letter. Do not use the letter C as the first character; transaction ids beginning with C are reserved for use by MSS.

Remote Prog

If the program resides in a remote region, specify the name by which the program is known there. You must specify Remote SysID before you can specify a remote program ID.

If you specify a remote system ID but leave this field blank, the local identifier for this program will be sent to the remote region.

Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - enables all the resource keys.
  • Off - disables all the resource keys.
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Active, Display

Click this to display the currently installed definition of this resource.

Active, Install

Click this to install (make active) this resource.

Delete

Click this to delete this PPT. This button is displayed only after you click Add.

Copy

Click this to create a new PPT, using the values set on this page as the basis for the new PPT. This button is displayed only after you click Add.

Dump

Click this to create and view dump information for this PPT. This button is displayed only after you click Add.

Parent topic: Pages for Creating Resources


CICS Sys62

Use this page to create a new Sys62 sys62. A Sys62 is a definition of an LU6.2 system connection.

The title bar gives details of the Sys62 you are editing and the resource group it belongs to.

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new Sys62.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Group List

Click this to display the CICS Group group_name page.

Add

Click this to save changes you have made to the page, refresh the page and add the new Sys62 to the group you specify in Grp. The button changes to Apply.

Name

Specify the name of this Sys62. Can be up to four characters: the first character must be A-Z, @, #, or $; trailing characters can be any of these, or 0-9. The name is forced to upper case.

Grp

Choose a group to which this Sys62 will belong. The list of groups from which you can choose include only those which can be edited by you.

Description

Specify a short description of the Sys62. Acceptable characters are A through Z, 0 through 9, $, @ and #.

LU Alias

Specify the parameter used to connect this definition to the LU6.2 protocol stack definition for this connection.

Mode Table

Specify the parameter that tells the LU6.2 protocol stack which Mode (or session characteristics) Table to use for this connection.

Partner Alias

Specify the parameter required to associate this definition with a peer server's definition within the LU6.2 protocol stack definitions.

APPLID

Specify the SNA Application ID of the peer partner server for this connection.

Net Name

Specify the network name that identifies the remote system. The name can be up to eight characters in length. The name follows assembler language rules. It must start with an alphabetic character. The acceptable characters are: A-Z 0-9 $ @ and #. Lower-case characters are converted to upper-case except when using the CREATE command.

Net Name is the APPLID of the remote system or region, unless you are defining an APPC or LUTYPE6.1 link to a VTAM generic resource group. If you are defining an LUTYPE6.1 link to a generic resource, Net Name must specify the generic resource name, not the APPLID of one of the group members. If you are defining an APPC link to a generic resource, Net Name can specify either the group’s generic resource name or the APPLID (member name) of one of the group members. However, if you specify a member name, and this CICS is not itself a member of a CICS Transaction Server for OS/390 generic resource, the connection must always be acquired by this CICS. For VTAM, the APPLID is the label of the remote ACF/VTAMÑ VBUILD TYPE=APPL statement. If you do not supply a Net Name, the CONNECTION name is used by default. You cannot have two or more APPC links with the same Net Name.

Session Max

Specify the maximum number of parallel sessions allowed to be active on this LU.

Transaction

Specify the permanent four-character transaction code to be attached to handle unsolicited input

Priority

Specify the facility-related priority to be used for work that is running with this as the primary facility.

In Service

Check this to enable this facility to default to (or start initially as) being “in service”.

SYNCLEVEL
Specify the SYNCLEVEL supported by the remote system. The SYNCLEVEL value is used to validate transactions running on Enterprise Server that use the EXEC CICS CONNECT PROCESS API for Distributed Transaction Processing. If the target system does not support the specified SYNCLEVEL value, the CONNECT PROCESS fails with INVREQ, as per the CICS API specification. Valid values are:
  • 1 - The target system supports SYNCLEVEL 1 only
  • 2 - The target system supports SYNCLEVEL 2
User ID

Specify the permanent user ID for this LU. Any work running against this facility will inherit the permissions of this user ID.

Language

Specify the default language for user interfaces connected to this facility.

Session Name

Specify the name for the session.

Attach

Specify the level of attach-time user security required for the connection:

  • Identify - Incoming attach requests must specify a user identifier. IDENTIFY is used when the connecting system has a security manager; for example, if it is another CICS system.
  • Local - The authority of the user is taken to be that of the link itself, and you rely on link security alone to protect your resource. Local must be specified if the PROTOCOL attribute on the CONNECTION definition is LU6.1.
  • Mixed - Incoming attach requests may be using either or both IDENTIFY or PERSISTENT security types. The security type actually used depends on the incoming attach request.
  • Persistent - Incoming attach requests must specify a user identifier and a user password on the first attach request. Subsequent attach requests require only the user identifier. This should be used only between a PWS (programmable workstation, for example, an IBM Personal System/2) and CICS.
  • Verify - Incoming attach requests must specify a user identifier and a user password. Enter Verify when the connecting system has no security manager and hence cannot be trusted. Do not specify Verify for CICS-to-CICS communication, because CICS does not send passwords.
Oper ID

Specify the three-character Operator ID associated with the permanent User ID - returned on ASSIGN OPID() command for transaction attached to this facility.

Oper Priority

Specify the operator priority for transactions run from this terminal. Specify this for a terminal that cannot be signed on, such as a printer. If you specify it for a terminal that can be signed on, it is overridden by the operator priority specified in the user's sign-on table entry. Defaults to 0(zero). Operator priority is one factor in determining a transaction's execution priority, which is the sum of:

  • Terminal priority
  • Transaction priority
  • Operator priority (this field)

The sum cannot be greater than 255.

Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - enables all of the resource keys
  • Off - disables all of the resource keys
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Delete

Click this to delete this Sys62. This button is displayed only after you click Add.

Copy

Click this to create a new Sys62, using the values set on this page as the basis for the new Sys62. This button is displayed only after you click Add.

Dump

Click this to create and view dump information for this Sys62. This button is only displayed after you click Add.

Parent topic: Pages for Creating Resources


CICS SysC

Use this page to create a new SysC. A SysC is a definition of a CCI system connection.

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new SysC.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Group List

Click this to display the CICS Group page group_name.

Add

Click this to save changes you have made to the page, refresh the page and add the new SysC to the group you specify in Grp. The button changes to Apply.

Name

Specify the name of this SysC. Can be up to four characters: the first character must be A-Z, @, #, or $; trailing characters can be any of these, or 0-9. The name is forced to upper case.

Grp

Choose a group to which this SysC will belong. The list of groups from which you can choose include only those which can be edited by you.

Description

Specify a description of the transaction program (can be up to 60 characters).

Machine Name

Specify the machine name; consists of the Local LU Alias of the client machine and the Mode used by CCIAPPC when issuing the APPC ALLOCATE verb to initiate a conversation with the server TP. The format is:

LUNAME.MODENAME

where the parameters are:

LUNAME | The Local LU Alias of the client machine. This name must also be defined as a Partner LU Alias on the server machine.
MODENAME | A Mode defined on both the client and server machines.
Protocol

Specify the CCI protocol to be used by this connection:

MF Node

Specify the text hostname or dotted decimal address of the target server.

MF Port

Specify the decimal value of the port that the target server listens on.

Net Name

Specify the name of the network over which the connection is established.

Session Max

Specify the maximum number of sessions that can use this connection.

Transaction

Specify the one- to four-character transaction ID. When MSS receives a request to start a transaction, it only looks at the first four characters of the TP name.

Priority

Specify the priority for transactions run from this terminal. Defaults to 0 (zero). Terminal priority is one factor in determining a transaction's execution priority, which is the sum of:

  • Terminal priority (this field)
  • Transaction priority
  • Operator priority

The sum cannot be greater than 255.

In Service

Check this to specify that the connection defined by this SysC is in service.

User ID

Specify a user ID to be associated with the connection. Mandatory if no sign-on takes place on the connection.

Language

Choose the national language in which messages are sent over the connection. You can choose English or Kanji.

Session Name

Specify the security name of the connection. Can be up to eight alphanumeric characters from the set A through Z, 0 through 9, $, @ and #.

Attach

Choose the level of security required when a user issues an attach request over this connection:

  • Identify - Incoming attach requests must specify a user ID.
  • Verify - Incoming attach requests must specify both a user ID and a password.
  • Persistent - The first attach request must specify both a user ID and a password, but subsequent attach requests require only a user ID.
  • Mixed - Incoming attach requests can specify either Identify or Persistent.
  • Local - The authority of the user is taken to be that of the link.
Oper ID

Specify an operator ID used for routing messages. Specify this for a terminal that cannot be signed on, such as a printer. If you specify an operator ID for a terminal that can be signed on, it is overridden by the operator ID specified in the user's sign-on table entry. Up to three alphanumeric characters.

Oper Priority

Specify the operator priority for transactions run from this terminal. Specify this for a terminal that cannot be signed on, such as a printer. If you specify it for a terminal that can be signed on, it is overridden by the operator priority specified in the user's sign-on table entry. Defaults to 0(zero). Operator priority is one factor in determining a transaction's execution priority, which is the sum of:

  • Terminal priority
  • Transaction priority
  • Operator priority (this field)

The sum cannot be greater than 255.

Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - enables all of the resource keys
  • Off - disables all of the resource keys
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that security key.

Delete

Click this to delete this SysC. This button is displayed only after you click Add.

Copy

Click this to create a new SysC, using the values set on this page as the basis for the new SysC. This button is displayed only after you click Add.

Dump

Click this to create and view dump information for this SysC. This button is displayed only after you click Add.

Parent topic: Pages for Creating Resources


CICS T-Type

Use this page to create a new T-type (terminal type definition).

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new T-type.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Group List

Click this to display the CICS Group page group_name.

Add

Click this to save changes you have made to the page, refresh the page and add the new T-type to the group you specify in Grp. When you click Add, the button changes to Apply.

Name

Specify a name for the T-type.

Grp

Choose a group to which this T-type will belong. The list of groups from which you can choose include only those that can be edited by you.

Description

Specify a description of the T-type. The text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.

Type

Choose the type of terminal device:

  • 3270 - A 3270 display device
  • Non-Facility - A non-physical device
  • Generic - Non-specific facility definition
  • ECI - External Call Interface dummy facility
  • System - A peer CICS or ES server
  • LU1-Printer or LU3-Printer - Printer device
  • Dialog Sys - Dialog System client facility
Shippable

Check this to indicate that this physical terminal definition may be shipped to a remote system in support of a transaction routing request. Ifa physical terminal definition is not marked shippable, then the target system must have the terminal explicitly defined as a remote terminal for the transaction routing request to succeed.

Map Size, Width

Specify the page width for the terminal type being defined. The width is defined as a number of columns, in the range 0 through 999. The default is 80.

Map Size, Height

Specify the page height for the terminal type being defined. The height is defined as a number of rows, in the range 0 through 999. The default is 24.

Alternate Map, Width

Specify the page width for the terminal type being defined, if you have specified an alternate screen size (non-default values for Alt Screen, Width and Alt Screen, Height). Alternate page width is defined as a number of columns, in the range 0 through 999. The default is 80. Unexpected results may occur if the number of columns is not the same as the number of columns you specify for Alt Screen, Width. Defaults to the values specified in Map Size, Width.

Alternate Map, Height

Specify the page height for the terminal type being defined, if you have specified an alternate screen size (non-default values for Alt Screen, Width and Alt Screen, Height). Alternate page height is defined as a number of rows, in the range 0 through 999. Unexpected results may occur if the number of rows is not the same as the number of rows you specify for Alt Screen, Height. Defaults to the values specified in Map Size, Height

OB Oper ID, Yes

Check this to enable MSS to use the outbound operator identifiers to support the BMS routing facilities required by this terminal type definition.

Outboard Fmt, Yes

Check this to enable MSS BMS to delegate part of the presentation formatting to the client facility.

ASCII

Choose whether or not this terminal type has an ASCII feature:

No | The terminal type does not have an ASCII feature
7 Bit | Terminals of this type are ASCII-7 terminals. All outbound data is translated to 7-bit ASCII, and all inbound data is translated to EBCDIC
8 Bit | Terminals of this type are ASCII-8 terminals. All outbound data is translated to 8-bit ASCII, and all inbound data is translated to EBCDIC
Send Size

Specify the size, in bytes, of the receive buffer of a terminal of this type. This represents the maximum amount of data that the terminal can receive, and depends on the capability of the device. Considerations of line quality might lead you to specify a buffer size that is less than the terminal type's maximum buffer size. A message longer than the receive buffer is broken into as many request units as are necessary. Defaults to 0 (zero). If you specify a zero buffer size, the message is not broken up; the whole message is presented.

Receive Size

Specify the maximum size, in bytes, of a request unit that can satisfy a receive request. The value you specify might be rounded down.

Routed Msg

Indicates whether or not messages are routed to a terminal of this type by the EXEC CICS ROUTE command. Check this to indicate that BMS is to route to this terminal messages that are destined for all terminals, as well as messages destined for this terminal. Leave unchecked to specify that no messages should be routed to this terminal, even if they are specifically destined for this terminal.

Logon Msg

Check this to specify that the logon transaction is initiated when a session is established and displays the logon message on the terminal. Automatic Transaction Initiation (ATI) is used to start the transaction, so you must check ATI. The transaction competes with any other ATI transactions for use of the terminal. If you check Lastline, the logon message does not overwrite any error message currently displayed.

Auto Connect

Check this to specify that a session is to be established with the terminal when the region starts up. Leave unchecked to specify that a session is to be established when the user signs on at the terminal.

ATI

Check this to enable a transaction to be automatically initiated on this terminal. If you leave this unchecked, you should check TTI to enable users to initiate transactions.

Create Sess

Check this to specify that a session can be initiated from a terminal of this type: EXEC START requests and Automatic Transaction Initiation (ATI) requests are allowed to create sessions automatically. Leave unchecked to specify that EXEC START requests and Automatic Transaction Initiation (ATI) requests are not allowed to create sessions automatically. Such requests are queued or rejected if a session has not been established.

TTI

Check this to enable users to initiate transactions at this terminal. If you leave this unchecked, you should check ATI to enable transactions to be automatically initiated.

NEP Class

Specify the transaction class of the node error program. Defaults to 0000 (zero), which indicates that the default node error program is to be used.

Signoff

Choose which action is to be taken when GNTRAN (CESF or user-defined transaction) is attached and attempts to sign off the terminal. If you are using RACF 1.9 or later, specify the TIMEOUT limit in the RACF segment:

No | The terminal is not automatically signed off in the absence of user input.
Signoff | When the specified time has elapsed after the last input from the operator, the terminal is automatically signed off from MSS.
Signoff/Logoff When the specified time has elapsed after the last input from the operator, the terminal is automatically signed off from MSS and then logged off from VTAM. (This is not supported for TCAM-attached terminals.) Signoff/Logoff is useful for an autoinstall model, because virtual storage is not wasted on entries for terminals that have been timed out. If GNTRAN fails to attach because of unprocessed data in the terminal buffer (resulting in a BID failure), the terminal will be signed off and logged off. GNTRAN will not run and will have no effect.
Note: You cannot change the value of this attribute when DEVICE(APPC) is specified. The default value in that case is Signoff(No).
Notify

Choose how the user is notified of system recovery. This option applies to the recovery of sessions for terminals in a CICS region running with either VTAM persistent sessions or with XRF. It is for use in situations where a terminal user may have to take action, such as to sign on again, after a CICS restart:

None | The user is not notified
Message | A message is displayed on the screen to say that the system has recovered. The message is specified in two BMS maps; DFHXRC1 and DFHXRC2 for XRF; and DFHXRC3 and DFHXRC4 for VTAM persistent sessions. These maps are in mapset DFHXMSG. If reduced takeover time is important, use MESSAGE rather than TRANSACTION. The terminal must be capable of displaying BMS maps, and ATI.must be checked, to specify this option.
Transaction | A transaction is initiated at the terminal. The name of the transaction is specified by the RMTRAN system initialization parameter. (The default transaction for RMTRAN is the one specified in the GMTRAN system initialization parameter: the good-morning transaction.) ATI must be checked to specify this option.
Option

Choose how MSS recovers the session and returns the terminal to normal service:

Sys Default | MSS selects the best recovery strategy based on session activity and the characteristics of the terminal.
Clear Receive | MSS sends a CLEAR request to reset the conversation state, or an UNBIND request if the session does not support the CLEAR request. MSS sends the CLEAR or UNBIND request only if the session was busy.
Release Sess | MSS sends an UNBIND request to clear the active session, if the session was busy.
Unconditional | MSS sends an UNBIND request to clear the active session, whether or not the session was busy.
None | The terminal session is not automatically recovered. If you checked Auto Connect, the terminal is automatically reconnected.
Last Line

Check this to specify that error messages are to be displayed at the bottom of the screen, starting at a position that enables the entire message to be shown at once. If messages are received in quick succession, an earlier message might be overwritten before the user has time to read it. Messages displayed in this way might have the additional attributes specified by Intensify, Color and Highlight. If you leave this unchecked, an error message is displayed at the current cursor position, and without any additional attributes.

Intensify

Check this to have error messages displayed in an intensified field (bold). This has an effect only if Last Line is checked.

Color (Diagnostic Display)

Choose the color in which error messages are to be displayed on a terminal of this type. A setting other than No takes effect only if Last Line is checked.

Highlight (Diagnostic Display)

Choose the type of highlighting to be used for error messages displayed on a terminal of this type. A setting other than No takes effect only if Last Line is checked.

Def. Screen, Width

Specify the default screen width for the 3270 terminal type being defined. This is the screen width that is used when a transaction definition specifies a default screen. Screen width is defined as columns, in the range 0 through 999. The default is 80. There is no validity checking; incorrect sizes might lead to unpredictable behavior.

Def. Screen, Height

Specify the default screen height for the 3270 terminal type being defined. This is the screen height that is used when a transaction definition specifies a default screen. Screen height is defined as rows, in the range 0 through 999 The default is 24. There is no validity checking; incorrect sizes might lead to unpredictable behavior.

Alt. Screen, Width

Specify the alternate screen width for the 3270 terminal type being defined. This is the screen width that is used when a transaction definition specifies an alternate screen. Screen width is defined as columns, in the range 0 through 999. The default is 80. There is no validity checking; incorrect sizes might lead to unpredictable behavior.

Alt. Screen, Height

Specify the alternate screen height for the 3270 terminal type being defined. This is the screen height that is used when a transaction definition specifies an alternate screen. Screen height is defined as rows, in the range 0 through 999 The default is 24. There is no validity checking; incorrect sizes might lead to unpredictable behavior.

APL Keyboard

Check this to specify that the terminal type has the APL keyboard feature.

APL Text

Check this to specify that the terminal type can support the APL text character set.

Audible Alarm

Check this to specify that the terminal type has the audible alarm feature.

Color

Check this to specify that the terminal type has the color feature, which enables colors to be selected for individual fields.

Dual case kbd

Check this to specify that the terminal has a typewriter keyboard. Leave this unchecked to specify that the terminal has an operator console keyboard. Both types of keyboard transmit both upper-case and lower-case data.

Copy (Device Properties)

Check this to specify that the terminal type has the copy feature.

Extended DS

Check this to specify that the terminal type supports extensions to the 3270 data stream. You must check this if Color or Hilight are checked.

Highlight

Check this to specify that the terminal type has the extended highlight feature, enabling individual fields or characters to be displayed in bold, reverse video, or blinking.

Katakana

Check this to specify that the terminal type is a Katakana terminal. Katakana terminals do not support mixed-case output. Upper-case characters appear as upper-case English, but lower-case characters appear as Katakana characters.

Light Pen

Check this to specify that the terminal type has the light pen selector feature. MSS emulates this feature using mouse clicks.

Form Feed

Check this to specify that the device has the form feed feature.

CGSCID

Specify the coded graphic character set global identifier (CGCSGID) that enables transaction programs to determine what character set is supported by this terminal. Defaults to 0,0, which means that the terminal type does not support this feature. The first field specifies the graphic character set global identifier (GCSGID), and the second field specifies the code page global identifier (CPGID).

Horizontal Form

Check this to specify that the device has the horizontal form feature. The devices that can use this feature are batch, batch data interchange, interactive, SCSPRT or LUTYPE4 logical units. If checked, BMS uses horizontal tabbing when formatting output documents. If unchecked, the HTAB option in the BMS map definition is ignored.

Vertical FF

Check this to specify that the device has the vertical form feature. The devices that can use this feature are batch, batch data interchange, interactive, SCSPRT or LUTYPE4 logical units. If checked, BMS uses vertical tabbing when formatting output documents. If unchecked, the VTAB option in the BMS map definition is ignored.

EWA Support

Check this to enable a 3270 device to shift its display into its alternate mode.

SOSI

Check this to specify that the terminal type supports mixed EBCDIC and DBCS fields.

PS

Check this to specify that the terminal type supports the programmed symbol facility. This facility enables you to use a maximum of six sets of 191 characters

Outline

Check this to specify that the terminal type supports field outlining.

Numeric Lock

Check this to enable the numeric lock.

Buffer

Check this to specify that BMS buffers formatted data streams that are sent to a terminal of this type, that is, when an application issues a series of SEND TEXT PRINT commands, MSS sends a page to the terminal only when it is full. Leave thus unchecked to specify that when an application issues a series of SEND TEXT PRINT commands, MSS sends a page to the terminal for every command issued, filling up the page by appending blank lines if necessary.

Print Adapter

Check this to specify that output BMS screens with the PRINT option set on are to be copied automatically to an attached printer.

Transparency

Check this to enable background transparency.

Query

Check this to enable MSS to use the QUERY structured field to determine the characteristics of the device.

Text KB

Check this to specify that the 3270 device has the text-keyboard feature.

Mag Stripe Rdr

Check this to specify that the terminal type has the magnetic stripe reader feature. MSS emulates this feature using mouse clicks.

Validation

Check this:

  • For 8775 devices to enable the extended validation feature, which allows fields to be defined as TRIGGER, MANDATORY FILL, or MANDATORY ENTER.
  • For 3290 devices to enable the validation feature, which allows fields to be defined as MANDATORY FILL or MANDATORY ENTER.
Partition Support

Check this to enable the device to use partitions. This option is not valid for SCS printers.

Build Chain

Check this to specify that MSS is to reassemble request units into a complete message before passing data from a terminal of this type to a transaction program. Leave this unchecked to specify that messages are to be received by the transaction program in individual request units.

User Area

Specify the size, in bytes, of the user area of a terminal of this type. Defaults to 0 (zero).

In Shared Stg

Check this to force the user area into shared storage such that it can be accessed by transactions that do not have this device as the primary facility.

Uppercase Trans

Choose how data entered in lower case is to be treated:

Yes | Data input in lower case is translated to upper case.
No | Data input in lower case is not translated to upper case.
Tranid | Transaction identifiers input in lower case are translated to upper case; not other input data is translated.
I/O Area

Specify the minimum and maximum sizes, in bytes, of the terminal I/O area to be passed to a transaction program when it issues a RECEIVE. If you enter a number in the first field, a terminal I/O area of at least that size is passed to the transaction program. If you specify values in both fields, and a message longer than that specified by the first field, but shorter than that specified by the second field is received, then a terminal I/O area of the maximum size is passed to the transaction program. A message longer than that specified by the second field causes the node abnormal condition program to send an exception response to the terminal. Defaults to 0,0. If you check ATI, you must specify a terminal I/O area of at least one byte.

Active, Display

Click this to display the currently installed definition of this resource.

Active, Install

Click this to install (make active) this resource.

Delete

Click this to delete this T-type. This button is displayed only after you click Add.

Copy

Click this to create a new T-type, using the values set on this page as the basis for the new T-type. This button is displayed only after you click Add.

Dump

Click this to create and view dump information for this T-type. This button is displayed only after you click Add.

Parent topic: Pages for Creating Resources


CICS Term

Use this page to create a new Term (terminal).

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new Term.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Group List

Click this to display the CICS Group group_name page.

Add

Click this to save changes you have made to the page, refresh the page and add the new Term to the group you specify in Grp. The button changes to Apply..

Name

Specify the name for this Term.

Grp

Choose a group to which this Term will belong. The list of groups from which you can choose include only those which can be edited by you.

Description

Specify a description for this Term.

Model

Choose whether or not this terminal definition can be used as a model terminal definition for autoinstall:

  • No - can be used only for a specific device that is not autoinstalled.
  • Yes - can be used as a model for autoinstall, as well as for a specific device that is not autoinstalled.
  • Only - can be used only as a model for autoinstall.
Model Name

Applicable only if Model is Yes or Only. Specify the name by which the definition is known to the Autoinstall Control Program. Specify a name of up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Defaults to the name of this Term.

Terminal Type

Specify the associated Typerterm definition, which must exist. Mandatory.

Net Name

Specify the terminal's network name. Mandatory if Model is 'Yes' or 'No'. The name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. The first character must be a letter.

Remote Name

Specify the remote name. Applicable only for remote terminals. Necessary only if it differs from the local terminal name.

Remote SysID

Specify the remote system ID that holds the terminal definition. Applicable only for remote terminals. This must correspond to one of:

  • The Local SYSID field in the SIT used to run the related remote MSS region.
  • The APPLID of another CICS system.
Transaction

Specify a transaction name. This specifies the only transaction that users can run from this terminal, apart from print and paging requests. Optional. If not specified, users can run any transaction from this terminal.

Priority

Specify the priority for transactions run from this terminal. Defaults to 0 (zero). Terminal priority is one factor in determining a transaction's execution priority, which is the sum of:

  • Terminal priority (this field)
  • Transaction priority
  • Operator priority

The sum cannot be greater than 255.

In Service

Check this to specify that this terminal is in service; that is, transactions can be initiated and messages sent.

Main Printer

Specify the printer used for handling print requests. This printer must be owned by the system that owns the terminal. The name can be up to four characters in length.

Prt. Copy

Check this to specify that the hardware copy feature (using the printer defined for this terminal) is used for print requests issued from this terminal.

Alternate Printer

Specify the printer used for handling print requests if the printer specified in Main Printer is unavailable. This printer must be owned by the system that owns the terminal. The name can be up to four characters in length.

Alt. Prt. Copy

Check this to specify that the hardware copy feature (using the alternate printer defined for this terminal) is to be used for print requests issued from this terminal.

User ID

Specify a user ID to be associated with the terminal. Mandatory if no sign-on takes place on the connection.

Language

Choose the national language in which messages are sent over the connection. You can choose English or Kanji.

Security Name

Specify the security name for the terminal. Required only if the terminal is owned by a remote system and the connection method is APPC. Can be up to eight alphanumeric characters from the set A through Z, 0 through 9, $, @ and #.

Attach

Choose the level of security required when a user issues an attach request from this terminal:

  • Identify - Incoming attach requests must specify a user ID
  • Verify - Incoming attach requests must specify both a user ID and a password
  • Persistent - The first attach request must specify both a user ID and a password, but subsequent attach requests require only a user ID
  • Mixed - Incoming attach requests may specify either Identify or Persistent
  • Local - The authority of the user is taken to be that of the link
Oper ID

Specify an operator ID to be used for routing messages. Specify this for a terminal that cannot be signed on, such as a printer. If you specify an operator ID for a terminal that can be signed on, it is overridden by the operator ID specified in the user's sign-on table entry. Up to three alphanumeric characters.

Oper Priority

Specify the operator priority for transactions run from this terminal. Specify this for a terminal that cannot be signed on, such as a printer. If you specify it for a terminal that can be signed on, it is overridden by the operator priority specified in the user's sign-on table entry. Defaults to 0 (zero). Operator priority is one factor in determining a transaction's execution priority, which is the sum of:

  • Terminal priority
  • Transaction priority
  • Operator priority (this field)

The sum cannot be greater than 255.

Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - enables all the resource keys
  • Off - disables all the resource keys
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Active, Display

Click this to display the currently installed definition of this resource.

Active, Install

Click this to install (make active) this resource.

Delete

Click this to delete this Term. This button is displayed only after you click Add.

Copy

Click this to create a new Term, using the values set on this page as the basis for the new Term. This button is displayed only after you click Add.

Dump

Click this to create and view dump information for this Term. This button is displayed only after you click Add.

Parent topic: Pages for Creating Resources


CICS TST

Use this page to view and edit the TST tst_name, selected from the CICS Group group_name page.

The title bar gives details of the TST you are editing and the resource group it belongs to.

Group List

Click this to display the CICS Group page group_name.

Add

Click this to save changes you have made to the page, refresh the page and add the new TST to the group you specify in Grp. The button changes to Apply.

Name

Specify the name of this TST.

Grp

Choose a group to which this TST will belong. The list of groups from which you can choose include only those which can be edited by you.

Description

Specify a description for the TST (can be up to 60 characters).

Recoverable

Check this to enable recovery of the temporary storage queue in the event of an abnormal termination of either MSS or the transaction processing the destination.

Name (Remote Queue)

Specify the name of a temporary storage queue.

SYSID

Specify the system or region in which the temporary storage queue resides. The name specified must be the same as that given in Name in the SysC or Sys62 definition.

Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - enables all the resource keys
  • Off - disables all the resource keys
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Security Keys, all

Choose a setting to apply to all the security keys:

  • On - enables all of the security keys
  • Off - disables all of the security keys
Security Keys, 1 - 64

Check any of the boxes 1 through 64 to activate that security key.

Delete

Click this to delete this TST. This button is displayed only after you click Add.

Copy

Click this to create a new TST, using the values set on this page as the basis for the new TST. This button is displayed only after you click Add.

Dump

Click this to create and view dump information for this TST. This button is displayed only after you click Add.

Parent topic: Pages for Creating Resources


CICS URIMAP

Use this page to create a new URIMAP.

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new URIMAP.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Click Apply to save changes you have made to the page and refresh the page.

Name
The name of this URIMAP definition. If you click Apply, the message "Update complete" is also displayed when the changes you have made to the URIMAP have been saved and the entry updated. Click Refresh to remove this message.
Description
A description of this URIMAP definition.
Status
Specifies whether this URIMAP definition is installed in an enabled or disabled state.
Usage
Specifies whether this URIMAP definition is for:
  • CICS as an HTTP server
  • CICS as an HTTP client
Universal Resource Identifier:
Scheme
The scheme component of the URI.
Port
The number of the port used by the user application when it communicates with a server.
Host
The host name, or IPv4 or IPv6 address, of the URI.
Path
The path component of the URI.
Associated CICS Resources:
TCPIPService
The name of a TCPIPSERVICE resource definition that defines an inbound port.
Analyzer
Indicates whether an analyzer program is used in processing the HTTP request.
Converter
The name of a converter program used to convert (or perform other processing) on the request and response.
Transaction
The name of an alias transaction used either to run the user application that composes the HTTP response, or to start the pipeline.
Program
The name of the user application program that composes the HTTP response.
Pipeline
Not supported for this release.
WebService
Not supported for this release.
Security Attributes:
Ciphers
A string of up to 56 hexadecimal digits that is interpreted as a list of up to 28 2-digit cipher suite codes.
Certificate
The label of the X.509 certificate that is used as the SSL client certificate during the SSL handshake.
Authenticate
Specifies whether to send basic authentication information in the HTTP response. Basic authentication can only be set when the ES region itself is secure.
Static Document Properties:
Not supported for this release.
Redirection:
Not supported for this release.
Parent topic: Pages for Creating Resources


CICS TCPIPSERVICE

Use this page to create a new TCPIPSERVICE.

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new TCP/IP service.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Click Apply to save changes you make to the page, and refresh the page.

Name
The name of this TCPIPSERVICE definition. If you click Apply, the message "Update complete" is also displayed when the changes you have made to the definition have been saved and the entry updated. Click Refresh to remove this message.
Description
A description of this definition.
URM
The name of a user-replaceable program that this service invokes.
Port No
The number of the port on which CICS listens for incoming client requests.
Status
Specifies the initial status of the service after installation, either OPEN if CICS is to begin listening for this service after installation, or CLOSE if not.
Protocol
The application level protocol used on the TCP/IP port.
Transaction
The ID of the CICS transaction to process new requests that this service receives.
Backlog
Not supported for this release.
TSQ Prefix
A code to identify items in the temporary storage queue (TSQ).
IP Address
Not supported for this release.
Socket Close
Not supported for this release.
Max Data Length
Not supported for this release.
Security:
Not supported for this release.
DNS Connection Balancing:
Not supported for this release.
Parent topic: Pages for Creating Resources


CICS XAT

Use this page to create a new XAT (XA-compliant database table).

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new XAT.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Group List

Click this to display the CICS Group page group_name.

Add

Click this to save changes you have made to the page, refresh the page and add the new XAT to the group you specify in Grp. The button changes to Apply.

Name

Specify the name of this XAT.

Grp

Choose a group to which this XAT will belong. The list of groups from which you can choose include only those that can be edited by you.

Description

Specify a short description of the XAT. Acceptable characters are A through Z, 0 through 9, $, @ and #.

Switch Module

Specify the location of the executable file (.dll on Windows, or .so on UNIX platforms) that contains the entry point that returns the xa_switch_t structure to the enterprise server.

DB Name

Specify the name by which the resource manager is known.

User ID

Specify a resource manager ID, used internally to identify a particular XA configuration. This must be unique within the enterprise server.

Password

Specify the password required for the User ID. If you are entering a new password, you have to confirm it by entering it in PW Verify.

PW Verify

Specify the password again, if you are creating a new password, to verify you have entered it correctly.

Open String, Free Format

Specify 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, Free Format

Specify 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.

Load Module

Choose an external resource manager that the server needs to communicate with on behalf of container-managed applications.

Load Module, Name

if you chose User in Load Module, specify the name of the module that supplies the run-time support for the database calls made by the application.

Parent topic: Pages for Creating Resources


CICS DOCTEMPLATE

Use this page to create a new DOCTEMPLATE.

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new template.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Click Add to save changes you have made to the page, refresh the page and add the new template to the group you specify in Grp. When you click Add, the button changes to Apply.

Name
The name of this template.
Grp
The group to which this resource belongs. Do not use group names beginning with "DFH" as these are reserved for use by CICS.
Description
A description of this template. This can be up to 58 characters long.
Append CR/LF
Specifies whether CICS deletes trailing spaces from, and appends carriage return/line feed to, each logical record of the template.
Content Type
The format of the template contents, either BINARY or EBCDIC. If you choose BINARY, when the template is loaded its contents are not parsed; if you select EBCDIC, the template contents are parsed as EBCDIC text.
Template Name
The name by which the template is know to application programs that use it. The name can be up to 48 characters long. If you do not enter a value, it defaults to the value of Name.
Template Type
The type for the source of the template.
Enter details for one of the following:
File
The name of a CICS file which contains the template. This name can be up to eight characters long.
TS Queue
The name of a temporary storage queue containing the template. This name can be up to 16 characters long.
TD Queue
The name of a transient storage queue containing the template. This name can be up to four characters long.
Program
The name of the CICS program that contains the template. This name can be up to 48 characters long. If you do not specify a value, the template name is used.
Exit Program
The name of the exit program that generates this template. This name can be up to eight characters long.
MVS PDS
The details of an MVS partitioned data set (PDS) containing the template.
  • DD Name, the name of the PDS. This name can be up to eight characters long. The default is "DFHHTML".
  • Member Name, the name of a member in the PDS. This name can be up to eight characters long.
HFS File
The name of a z/OS UNIX System Services file containing the template. This can be either the absolute name including all directories and beginning with a slash, or a name relative to the home directory of the CICS region. The name can be up to 255 characters long.
Parent topic: Pages for Creating Resources


CICS TRANCLASS

Use this page to create a new TRANCLASS. A TRANCLASS resource defines the characteristics of a transaction class.

Transactions that are defined as belonging to a transaction class are subject to scheduling constraints before they are allowed to execute. If transactions belonging to an active transaction class are already running, any new transactions are queued. Use the MaxActive attribute to specify the maximum number of transactions of this class that you want to run simultaneously.

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new TRANCLASS.

If you displayed this page by clicking New on a previous page, some values on this page might already be set to default values.

Group List

Click this to display the CICS Group page group_name.

Add

Click this to save changes you have made to the page, refresh the page and add the new TRANCLASS to the group you specify in Grp. The button changes to Apply.

Name

Specify the name of this TRANCLASS. Can be up to 60 characters.

Grp

Choose a group to which this TRANCLASS will belong. The list of groups from which you can choose includes only those which can be edited by you.

Description

Specify a description of the resource (can be up to 60 characters).

MaxActive

Specify the maximum number of transactions in this transaction class that are allowed to be active, in the range 0 through 999.

PurgeThresh

Purge threshold defines a limit to the number of transactions queuing for this transaction class. After this limit is reached, transactions are purged. Specify a threshold:

  • NO - no limit
  • number - purge threshold number (1 - 1000000)
Note: Not currently supported.
Install

Click this to install and make this resource active.

Delete

Click this to delete this TRANCLASS. This button is displayed only after you click Add.

Copy

Click this to create a new TRANCLASS, using the values set on this page as the basis for the new one. This button is displayed only after you click Add.

Dump

Click this to create and view dump information for this TRANCLASS. This button is also displayed only after you click Add.

Parent topic: Pages for Creating Resources


CICS PIPELINE

Use this page to create a new PIPELINE.

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new PIPELINE.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Click Apply to save changes you have made to the page and refresh the page.

Name
The name of this PIPELINE definition. If you click Apply, the message Update complete is also displayed when the changes you have made to the PIPELINE have been saved and the entry updated. Click Refresh to remove this message.
Description
A description of this PIPELINE definition.
Status

Choose the status of the PIPELINE:

  • Enable - the PIPELINE is enabled.
  • Disabled - the PIPELINE is disabled.
Resp Wait
  • DEFT - indicates the default value of the transport protocol. HTTP is 10 seconds. MQ is 60 seconds.
  • 0-9999 - the number of seconds that an application should wait for a response message from the service.
Config File
Shows the fully qualified pipeline configuration file.
Shelf
Must reference a valid directory, but currently unused.
WebSvc Dir
Shows the fully qualified name of the web service binding directory. When the PIPELINE is installed, this directory is scanned for .wsbind files and a WEBSERVICE resource is created and installed for each file found.
Parent topic: Pages for Creating Resources


CICS WEBSERVICE

Use this page to create a new WEBSERVICE.
Note: The recommended approach is to let the install of a PIPELINE dynamically create the appropriate WEBSERVICE resources. A WEBSERVICE will be created for each .wsbind file found in the WSDIR directory which is specified in the PIPELINE definition.

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new WEBSERVICE.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Click Apply to save changes you have made to the page and refresh the page.

Name

The name of this WEBSERVICE definition. If you click Apply, the message Update complete is also displayed when the changes you have made to the WEBSERVICE have been saved and the entry updated. Click Refresh to remove this message.

Description

Shows a description of this WEBSERVICE definition.

Validation

Specifies whether validation of SOAP messages against the associated schema will be performed. This is not currently supported and so only ‘No’ is a valid option.

Pipeline

Shows the name of the PIPELINE associated with this WEBSERVICE.

WSBind

Shows the fully qualified location of the web service binding file.

WSDL File

Shows the fully qualified location of the WSDL file (currently unused).

Archive File

Unused.

Parent topic: Pages for Creating Resources


Pages for Viewing and Editing Resources

  • CICS DCT - dct_name (group_name)
  • CICS FCT - fct_name (group_name)
  • CICS JCT - jct_name (group_name)
  • CICS PCT - pct_name (group_name)
  • CICS PLT - plt_name (group_name)
  • CICS PPT - PPT_name (group_name)
  • CICS Sys62 - sys62_name (group_name)
  • CICS SysC - sysc_name (group_name)
  • CICS T-Type - ttype_name (group_name)
  • CICS Term - term_name (group_name)
  • CICS TST - tst_name (group_name)
  • CICS XAT - xat_name (group_name)
  • CICS URIMAP - urimap_name (group_name)
  • CICS TCPIPSERVICE - tcpipservice_name (group_name)
  • CICS DOCTEMPLATE - doctemplate_name (group_name)
  • CICS TRANCLASS trnclass_name (group_name)
  • CICS PIPELINE - pipeline_name (group_name)
  • CICS WEBSERVICE - webservice_name (group_name)
Parent topic: Resources


CICS DCT - dct_name (group_name)

Use this page to view and edit the DCT dct_name, selected from the CICS Group group_name page.

The title bar gives details of the DCT you are editing and the resource group it belongs to.

Group List

Click this to display the CICS Group page group_name.

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 group in which the DCT resides.

Name

Shows the name for this DCT.

Description

Specify a description for this DCT (can be up to 60 characters).

Type

Choose the destination for transient data:

  • Intra-Part - intrapartition
  • Indirect - indirect
  • Extra-Part - extrapartition
  • Internal Rdr - the internal reader to which CICS applications can direct a JCL jobstream for execution by the JCL engine
Indirect Name

Specify the symbolic name of the indirect destination. The symbolic name is used when writing to the destination. The name can be one to four characters in length. This control has an effect only if you selected Indirect in the Type control.

Recoverable

Check this to enable recovery of the destination in the event of an abnormal termination of either MSS or the transaction processing the destination. This control has an effect only if you selected Intra in the Type control.

Name (Remote Queue)

Specify the name of a remote transient data destination.

SYSID

Specify the system or region in which the remote transient data destination resides. The name specified must be the same as that given in Name in the SysC or Sys62 definition.

Transaction

Specify the name of the transaction that is to be automatically initiated when the trigger level specified in Trigger Level is reached. If no transaction is specified, or Trigger Level is set to 0, some other means must be used to schedule transactions to read records from the destinations.

Terminal

Specify the terminal associated with the transient data destination. The terminal must be defined to MSS.

Trigger Level

Specify the number of records to be accumulated before a task is automatically initiated to process them. The maximum number you can enter is 32767.

File Name

Specify the filename of the extrapartition file.

File Path

Specify the pathname of the folder that contains the extrapartition file.

Extension

Specify the filename extension of the extrapartion file.

Fileshare

Specify the name of the stand-alone Fileshare server that controls this file (if required).

Record Max

Specify the maximum length of a record in the extrapartition file.

Record Min

Specify the minimum length of a record in the extrapartition file.

Initial State

Choose the initial status of the data set:

  • Open - the data set is opened by system initialization.
  • Closed - the data set remains closed until you indicate that you want to open it.
Type (Extra-partition File Characteristics)

Choose whether the file is line sequential:

  • Normal - the file is not line sequential.
  • Line Sequential - the file is line sequential.
Print Attributes

Choose whether or not a forms control character is contained in the first position of each record:

  • No Control - records have no forms control character.
  • ASA - records contain a form control character that is in ASA format.
  • Machine - records contain a form control character that is in machine format.
I/O Type

Choose the type of input/output:

  • Input - input data.
  • Output - output data.
  • Read Backwards - input data read from the end of the dataset to the beginning.
Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - enables all the resource keys
  • Off - disables all the resource keys
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Active, Display

Click this to display the currently installed definition of this resource.

Active, Install

Click this to install (make active) this resource.

Delete

Click this to delete this DCT. You see this button only if you have editing permissions for the group to which the DCT belongs.

Copy

Click this to create a new DCT using the entries specified on this page.

Dump

Click this to create and view dump information for this DCT.

Parent topic: Pages for Viewing and Editing Resources


CICS FCT - fct_name (group_name)

Use this page to view and, if you have the required permissions, to edit the FCT fct_name, selected from the CICS Group group_name page.

The bar at the top of the page gives details of the FCT you are editing and the resource group it belongs to.

Group List

Display the CICS Group page group_name.

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 group in which the FCT resides.

Name

Shows the name for this FCT

Description

Specify a description for this FCT (can be up to 60 characters).

Type

Choose the file type:

  • KSDS - Key sequence data set
  • ESDS - Entry sequence data set
  • RRDS - Relative record data set
  • Alt Index - Alternate index
  • Undefined - Remote file (You must specify Remote SYSID.)

You must uncheck Use Catalog before you can specify a file type. This is because if you use the catalog this information is stored there, not in the FCT entry.

Format

Specify the format for the file. You must uncheck Use Catalog before you can choose a file format. This is because if you use the catalog this information is stored there, not in the FCT entry.

LRECL Min

Specify the minimum logical record length of the file, in bytes, in the range 1 through 32767. This must not be greater than the value of Max LRECL.

For RSDS fixed-length records, set this value equal to Max LRECL. Not applicable to VSAM records.

You must uncheck Use catalog before you can specify a minimum logical record length. This is because if you use the catalog this information is stored there, not in the FCT entry.

LRECL Max

Specify the maximum logical record length of the file, in bytes in the range 1 through 32767. This must not be less than the value of Min LRECL.

For RSDS fixed-length records, set this value equal to Min LRECL. Not applicable to VSAM records.

Key Position

For files of type KSDS or ALT, specify the byte number at which the record key begins in the range 1 through 32767. Bytes are numbered from 1.

Key Length

For files of type KSDS or ALT, specify the length of the record key in bytes (within the range 1 through 32767). The value "Key position+Key length-1" must not be greater than Min LRECL.

For files of type Undefined, specify the length of the record key, which must not be greater than Max LRECL.

Use Catalog

Check this if you want to use the catalog to store information about the file. If checked, certain parameters on this page become irrelevant; the description for each parameter indicates whether Use Catalog affects that parameter.

AIX Base

Specify the base filename for an alternate index. MSS references alternate indexes by a user-assigned name. This connects the alternate index definition to the base file.

Dataset Name

Specify the data set name for this file as used on the mainframe. You must check Use Catalog before you can specify a data set name. This is because the catalog uses this information.

Status

Choose whether the file is accessible to transactions:

  • Enabled - the file is accessible to transactions at system startup.
  • Disabled - the file is not accessible to transactions at system startup. A disabled file returns the reference "DISABLED". This can cause problems for some applications; if this is true for your application, set Unenable instead.
  • Unenabled - the file is not accessible to transactions at system startup. An unenabled file returns a reference "NOTOPEN", which can be handled by those applications that cannot handle a "DISABLED" reference.

The value set by this control is ignored if the file resides on a remote system.

Access

Check one or more boxes to set the read/write permissions for the file:

  • Read - enables applications to read records from the file
  • Add - enables applications to add records to the file
  • Browse - enables applications to browse the file
  • Delete - enables applications to delete records from the file
  • Update - enables applications to update records in the file
  • Exclusive - CICS Exclusive Control. Enables an application to gain exclusive control of a record within a file.
Set

Check one or more boxes to set various file parameters:

  • Start Open - check this to indicate that the file is to be opened at system startup. If you want the file to be opened at system startup and accessible to transactions, you must also select Enabled in the Status select box.
  • Start Empty - check this to indicate that the current contents of the file are to be deleted at system startup
  • Backward Recovery - check this to indicate that the file is a protected resource changes to which can be backed out. The file must be accessed through a Fileshare server.
  • Forward Recovery - check this to indicate that journals are to be used to record changes to the file to enable forward recovery. The file must be accessed through a Fileshare server.
  • Allow Duplicate Keys - check this if the file can have duplicate keys. The file must be an alternate index (Type set to Alt index) and you must have unchecked Use Catalog, because if you use the catalog this information is stored there, not in the FCT entry.
  • EBCDIC Collating Sequence - check this to indicate that the EBCDIC collating sequence is to be used. You must uncheck Use Catalog before you can check this, because if you use the catalog this information is stored there, not in the FCT entry.
Remote SYSID

Specify the system ID of the remote system on which the file resides. The name specified must be the same as that given in Name in the SysC or Sys62 definition.

Use Catalog must be unchecked before you can specify a system ID for the remote system. This is because the catalog is used only for storing information about files held locally.

Remote File

Specify the name of the file on the remote system. Use Catalog must be unchecked before you can specify a name for a remote file. This is because the catalog is used only for storing information about files held locally.

Override File Name

Specify the filename of the physical file if you want to override the default. Do not include the file extension. Can be up to 255 characters.

If you do not specify this entry, the physical file name defaults to the name of the FCT entry.

You cannot use this default if you specify a Fileshare server; you must specify a physical file name.

Use Catalog must be unchecked before you can specify a filename. This is because if you use the catalog this information is stored there, not in the FCT entry.

File Extension

Specify the file extension of the physical file if you want to override the default. Can be up to 3 characters. Use Catalog must be unchecked before you can specify an extension. This is because if you use the catalog this information is not required.

File Path

Specify the path of the physical file if you want to override the default. Do not include the filename or file extension. Can be up to 255 characters. Use catalog must be unchecked before you can specify a path. This is because if you use the catalog this information is stored there, not in the FCT entry.

Fileshare Server

Specify the ID of the Fileshare server on which the file resides. Can be up to 16 characters. You must uncheck Use Catalog before you can specify a Fileshare server. This is because if you use the catalog this information is stored there, not in the FCT entry.

Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - Enables all the resource keys
  • Off - Disables all the resource keys
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Active, Display

Click this to display the currently installed definition of this resource.

Active, Install

Click this to install (make active) this resource.

Delete

Click this to delete this FCT. You see this button only if you have editing permissions for the group to which the FCT belongs.

Copy

Click this to create a new FCT using the entries specified on this page.

Dump

Click this to create and view a dump of the FCT.

Parent topic: Pages for Viewing and Editing Resources


CICS JCT - jct_name (group_name)

Use this page to view and, if you have the you have the required permissions, edit the JCT jct_name, selected from the CICS Group group_name page.

The title bar gives details of the JCT you are editing and the resource group it belongs to.

Group List

Click this to display the CICS Group group_name page.

Apply

Click this to save changes you have made to the page and refresh the page. This button is only displayed if you have permission to edit the group in which the JCT resides.

Name

Shows the name of this JCT.

Description

Specify adescription of the JCT. The description can be up to 60 characters long.

Type

Choose the type of journal:

  • Disk 1 - a journal on disk that has one data set to be reused when full.
  • Disk 2 - a journal on disk that has two data sets to be used alternately. You must specify this to minimize operator involvement during a takeover.
  • Disk 2 Pause - a journal on disk that has two data sets to be used alternately. When the second data set is full, the system is paused to enable the operator to copy the data sets to another location before resuming with the first data set.
  • SMF - mainframe System Management Facility format.
  • Tape 1 - a journal on one tape drive.
  • Tape 2 - a journal on two tape drives.
File Name

Specify the filename of the journal.

File Path

Specify the pathname of the journal file.

Extension

Specify the filename extension of the journal file.

Fileshare

Specify the name of the Fileshare server that controls this data set.

Record Max

Specifies the maximum length of a record in the journal file.

Record Min

Specifies the minimum length of a record in the journal file.

Initial State

Choose the initial status of the journal:

  • New - a new journal data set is created at system initialization.
  • Append - data is appended to an existing journal data set.
Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - enables all the resource keys
  • Off - disables all the resource keys
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Delete

Click this to delete this JCT. You see this button only if you have editing permissions for the group to which the JCT belongs.

Copy

Click this to create a new JCT that uses the values in this JCT.

Dump

Click this to create and view dump information for this JCT.

Parent topic: Pages for Viewing and Editing Resources


CICS PCT - pct_name (group_name)

Use this page to view and, if you have the required permissions, to edit the PCT pct_name.

The title bar gives the name (pct_name) of the PCT you are editing and the resource group (group_name) it belongs to.

Click Apply to save changes you make to the page then refresh the page. This button is displayed only if you have permission to edit the group in which the PCT resides.

Group List

Click this to display the CICS Group page group_name.

Name

Shows the name for this PCT.

Description

Specify a description of the transaction program (can be up to 60 characters).

Program Name

For local programs only, specify the name of the application program to be run when this transaction is invoked. Leave this field blank if you enter a value in the remote system ID field.

Can be up to eight characters (A-Z, 0-9, #, @, or $). The name is translated to upper case.

Work Area

Specify the size of the transaction program's Transaction Working Area (TWA) in bytes, in the range 0 through 32767.

Remote SysID

Specify the system ID of the remote system. The name specified must be the same as that given in Name in the SysC or Sys62 definition.

Remote PCT

Specify the transaction ID of the transaction program on the remote system. You must specify Remote SysID before you can specify a transaction ID.

Can be up to four alphanumeric characters, the first of which must be a letter. Do not use the letter C as the first character; transaction IDs beginning with C are reserved for use by MSS.

Status

Choose a status for the transaction program:

  • Enabled - the transaction program is enabled.
  • Disabled - the transaction program is disabled.
In Doubt

Choose what is to happen if a transaction program using intersystem communication abends at a critical moment during syncpoint or abend processing:

  • Backout - the effects of the transaction are backed out using ROLLBACK. To use this option, files used by the transaction program must have Backward recovery checked on the FCT page.
  • Commit - any changes are committed.
  • Wait - critical resources are locked until the session has recovered, and are then backed out or committed in step with the remote system.
Upper Case

Check this if you want the transaction program to translate input into upper case

Tracing

Choose the type of tracing to be performed for the transaction program:

  • None - No tracing is performed.
  • Normal - Tracing is performed.
  • Special - Special tracing is performed.
Dynamic Route

Check this to have the program status (local or remote) determined dynamically at user invocation time. If this is unchecked, the program status is made local or remote according to the value of System ID.

Security

Use these check boxes to control the way in which resource authorization checks are performed. If they are not checked, the only check performed will be to confirm that the user has authority to run the transaction. If you check RLS (Resource Level Security), Enterprise Server will check the user's authorization for all resources that the transaction accesses (e.g. file access, TDQ, TSQ, LINK, DPL, START and so on). Checking CMD(for Command) will check the authorization on all the EXEC CICS command operations (e.g. EXEC CICS SET/ENABLE/DISABLE).

Note that IBM Category 3 Transactions do not have security checking at all, so the transactions are allowed for everyone with no authorization calls.

Priority

Specify the transaction priority of the transaction program in the range 0 through 255, where 255 is the highest priority.

The priority of a transaction is the sum of:

  • The terminal priority
  • The transaction priority (this field)
  • The operator priority

This sum must not be greater than 255.

Dump on ABEND

Check this to create a program dump if the transaction program abends.

3270 Screen

Specify the screen size to be used by the transaction program. Select:

  • Default to use the default screen size (as defined in the Typeterm entry).
  • Alternate to use the alternate screen size (as defined in the Typeterm entry).
Inbound

Check this to indicate that this transaction can be initiated by an inbound user action.

Input Timeout

Specify the maximum time in seconds allowed for operator response to an explicit CICS RECEIVE, WEB OPEN, WEB SEND, WEB RECEIVE, or WEB CONVERSE command before this transaction is abended. A value of 0 indicates that there is no timeout, and the system will wait indefinitely for a response.

Check Use System Value to use the system wide value for Input Timeout (as shown on the ESMAC Control screen) rather than the PCT entry.

Runaway Timeout

Specify the maximum continuous period of time in seconds that the region will allow this transaction to run without making a CICS, EZASOKET or WebSphere MQ API call. When this time is exceeded, the transaction is abended. A value of 0 indicates that there is no timeout.

Check Use System Value to use the system wide value for Runaway Timeout (as shown on the ESMAC Control screen) rather than the PCT entry.

Deadlock Timeout

Specify the maximum time in seconds that the region will permit this transaction to wait for a resource that has been locked by another process. A value of 0 indicates that there is no timeout.

Check Use System Value to use the system wide value for Deadlock Timeout (as shown on the ESMAC Control screen) rather than the PCT entry.

Transaction Threshold

Specify the maximum length of time in seconds that a transaction can run before a message is logged to the console to indicate that it has exceeded its threshold. A value of 0 indicates that there is no threshold.

Check Use System Value to use the system wide value for the transaction time threshold (as shown on the ESMAC Control screen) rather than the PCT entry.

TRANCLASS

Specify the name of the transaction class to which the transaction belongs. The reserved name DFHTCL00 is used to indicate that the transaction does not belong to any transaction class.

Can be up to eight characters (A-Z, 0-9, #, @, or $).

Resource Keys, all

Choose a setting to apply to the resource keys:

  • On - enables all the resource keys.
  • Off - disables all the resource keys.

Check any of the boxes 1 through 24 to activate that resource key.

Security Keys, all

Choose a setting to apply to the security keys:

  • On - enables all the security keys.
  • Off - disables all the security keys.

Check any of the boxes 1 through 64 to activate that security key.

Active

Click Display to display the currently installed definition of this resource.

Click Install to install (make active) this resource.

Delete

Click this to delete this PCT. You see this button only if you have editing permissions for the group to which the PCT belongs.

Copy

Click this to create a new PCT, using the values set on this page as the basis for the new PCT.

Dump

Click this to create and view dump information for this PCT.

Parent topic: Pages for Viewing and Editing Resources


CICS PLT - plt_name (group_name)

Use this page to view and edit the PLT plt_name, selected from the CICS Group group_name page.

The title bar gives details of the PLT you are editing and the resource group it belongs to.

Group List

Click this to display the CICS Group page group_name.

Apply

Click this to save changes you have made to the page, and refresh the page. You see this button only if you have permission to edit the PLT.

Name

Shows the name of the PLT.

Description

Specify a description of the PLT (can be up to 60 characters).

01 - nn

Shows a numbered list of programs.

Note that, if you can edit the PLT, there is always a blank field added at the end of the list.

You can add a new program in the blank field, if required. If you do so, you must click Apply. The page is refreshed, and the new program is added to the list.

You can edit a program name by clicking in the name and making your changes. Your changes do not take effect until you click Apply.

You can change the order of the programs in the PLT. Use Down arrow button to move a program down the list. Use Up arrow button to move a program up the list.

Delete an entry in the PLT by clicking Delete button.

Run once/Run in each process

Click Run once to specify that the program should only run once, when the PLT is first initiated. Click Run in each process to specify that the program should run every time the PLT is initiated.

Delete

Click this to delete this PLT. You see this button only if you have editing permissions for the group to which the PLT belongs.

Copy

Click this to create a new PLT, using the values set on this page as the basis for the new PLT.

Dump

Click this to create and view dump information for this PLT.

Parent topic: Pages for Viewing and Editing Resources


CICS PPT - PPT_name (group_name)

Use this page to edit the PPT PPT_name, selected from the CICS Group group_name page.

The bar at the top of the page gives details of the PPT you are editing and the resource group it belongs to.

Group List

Click this to display the CICS Group page group_name.

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 group in which the PPT resides.

Name

Shows the name for this PPT.

Description

Specify a description of the transaction program (can be up to 60 characters).

Status

Choose a status for the program:

  • Enabled - enables this program to be used in a normal manner.
  • Disabled - prevents the program from being used until specifically enabled using master terminal services.
Type

Choose a type for the resource:

  • Program - this resource is a program.
  • Data Area - this resource is a data table.
Resident

Check this if you want to enable this program to reside in the application server's program cache after it has been loaded.

Commarea

Specify the amount of storage to be allocated to the communications area (COMMAREA) to enable MSS to behave like mainframe CICS. The size is in the range 0 through 32767. The effect of this is that when a program is passed a COMMAREA smaller than the COMMAREA defined in the program, the passed COMMAREA is automatically extended in length to fill the defined space.

Language

Choose the language the program is written in.

Save, Working Storage

Check this to have load requests ignored if the program is already in storage.

Uncheck this to have a fresh copy of the program loaded every time a load request for the program is issued.

Remote SysID

If the program resides in a remote region, specify the 4-character, remote system identifier (as defined in the TCT).

If the program resides in the local region, leave this field blank.

Rmt Trans ID

Specify the transaction ID of the transaction program on the remote system. A System ID must be specified before a transaction ID can be specified.

The remote transaction ID can be up to four alphanumeric characters, the first of which must be a letter. Do not use the letter C as the first character; transaction IDs beginning with C are reserved for use by MSS.

Remote Prog

If the program resides in a remote region, specify the name by which the program is known there. Remote SysID must be specified before a remote program ID can be specified.

If you specify a remote system ID but leave this field blank, the local identifier for this program will be sent to the remote region.

Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - enables all the resource keys
  • Off - disables all the resource keys
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Active, Display

Click this to display the currently installed definition of this resource.

Active, Install

Click this to Install (make active) this resource.

Delete

Click this to delete this PPT. You see this button only if you have editing permissions for the group to which the PPT belongs.

Copy

Click this to create a new PPT using the entries specified on this page.

Dump

Click this to create and view a dump of this PPT.

Parent topic: Pages for Viewing and Editing Resources


CICS Sys62 - sys62_name (group_name)

Use this page to view and edit the Sys62 sys62, selected from the CICS Group group_name page. A Sys62 is a definition of an LU6.2 system connection.

The title bar gives details of the Sys62 you are editing and the resource group it belongs to.

Group List

Click this to display the CICS Group group_name page.

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 group in which the Sys62 resides.

Name

Shows the name of this Sys62.

Description

Specify a short description of the Sys62. Acceptable characters are A through Z, 0 through 9, $, @ and #.

LU Alias

Specify the parameter used to connect this definition to the LU6.2 protocol stack definition for this connection.

Mode Table

Specify the parameter that tells the LU6.2 protocol stack which Mode (or session characteristics) Table to use for this connection.

Partner Alias

Specify the parameter required to associate this definition with a peer server's definition within the LU6.2 protocol stack definitions.

APPLID

Specify the SNA Application ID of the peer partner server for this connection.

Net Name

Specify the network name that identifies the remote system. The name can be up to eight characters in length. The name follows assembler language rules. It must start with an alphabetic character. The acceptable characters are: A-Z 0-9 $ @ and #. Lower-case characters are converted to upper case except when using the CREATE command.

Net Name is the APPLID of the remote system or region, unless you are defining an APPC or LUTYPE6.1 link to a VTAM generic resource group. If you are defining an LUTYPE6.1 link to a generic resource, Net Name must specify the generic resource name, not the APPLID of one of the group members. If you are defining an APPC link to a generic resource, Net Name can specify either the group’s generic resource name or the APPLID (member name) of one of the group members. However, if you specify a member name, and this CICS is not itself a member of a CICS Transaction Server for OS/390 generic resource, the connection must always be acquired by this CICS. For VTAM, the APPLID is the label of the remote ACF/VTAMÑ VBUILD TYPE=APPL statement. If you do not supply a Net Name, the CONNECTION name is used by default. You cannot have two or more APPC links with the same Net Name.

Session Max

Specify the maximum number of parallel sessions allowed to be active on this LU.

Transaction

Specify the permanent four character transaction code to be attached to handle unsolicited input.

Priority

Specify the facility related priority to be used for work that is running with this as the primary facility.

In Service

Check this to enable this facilityto default to (or start initially as) being “in service”.

SYNCLEVEL
Specify the SYNCLEVEL supported by the remote system. The SYNCLEVEL value is used to validate transactions running on Enterprise Server that use the EXEC CICS CONNECT PROCESS API for Distributed Transaction Processing. If the target system does not support the specified SYNCLEVEL value, the CONNECT PROCESS fails with INVREQ, as per the CICS API specification. Valid values are:
  • 1 - The target system supports SYNCLEVEL 1 only
  • 2 - The target system supports SYNCLEVEL 2
User ID

Specify the permanent user ID for this LU. Any work running against this facility will inherit the permissions of this user ID.

Language

Specify the default language for user interfaces connected to this facility.

Session Name

Specify the name for the session.

Attach

Specify the level of attach-time user security required for the connection:

  • Identify - Incoming attach requests must specify a user identifier. IDENTIFY is used when the connecting system has a security manager; for example, if it is another CICS system.
  • Local - The authority of the user is taken to be that of the link itself, and you rely on link security alone to protect your resource. Local must be specified if the PROTOCOL attribute on the CONNECTION definition is LU6.1.
  • Mixed - Incoming attach requests may be using either or both IDENTIFY or PERSISTENT security types. The security type actually used depends on the incoming attach request.
  • Persistent - Incoming attach requests must specify a user identifier and a user password on the first attach request. Subsequent attach requests require only the user identifier. This should be used only between a PWS (programmable workstation, for example, an IBM Personal System/2) and CICS.
  • Verify - Incoming attach requests must specify a user identifier and a user password. Enter Verify when the connecting system has no security manager and hence cannot be trusted. Do not specify Verify for CICS-to-CICS communication, because CICS does not send passwords.
Oper ID

Specify the three-character operator ID associated with the permanent user ID - returned on ASSIGN OPID() command for transaction attached to this facility.

Oper Priority

Specify the operator-related priority for transactions running against this facility.

Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - enables all of the resource keys
  • Off - disables all of the resource keys
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Delete

Click this to delete this Sys62. You only see this button if you have editing permissions for the group to which the Sys62 belongs.

Copy

Click this to create a new Sys62, using the values set on this page as the basis for the new Sys62.

Dump

Click this to create and view dump information for this Sys62.

Parent topic: Pages for Viewing and Editing Resources


CICS SysC - sysc_name (group_name)

Use this page to view and edit the SysC sysc_name, selected from the CICS Group group_name or CICS Startup List startup_list page. A SysC is a definition of a CCI system connection.

The title bar gives details of the SysC you are editing and the resource group it belongs to.

Group List

Click this to display the CICS Group page group_name.

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 group in which the SysC resides.

Name

Shows the name of this SysC.

Description

Specify a description of the transaction program (can be up to 60 characters).

Machine Name

Specify the machine name; consists of the Local LU Alias of the client machine and the Mode used by CCIAPPC when issuing the APPC ALLOCATE verb to initiate a conversation with the server TP. The machine name must be specified in the following format:

LUNAME.MODENAME

where the parameters are:

LUNAME | The Local LU Alias of the client machine. This name must also be defined as a Partner LU Alias on the server machine.
MODENAME | A Mode defined on both the client and server machines.
Protocol

Specify the CCI protocol to be used by this connection.

MF Node

Specify the text hostname or dotted decimal address of the target server.

MF Port

Specify the decimal value of the port that the target server listens on.

Net Name

Specifiy the name of the network over which the connection is established.

Session Max

Specify the maximum number of sessions that can use this connection.

Transaction

Specify the one- to four-character transaction ID. When MSS receives a request to start a transaction, it only looks at the first four characters of the TP name.

Priority

Specify the priority for transactions run from this terminal. Defaults to 0 (zero). Terminal priority is one factor in determining a transaction's execution priority, which is the sum of:

  • Terminal priority (this field)
  • Transaction priority
  • Operator priority

The sum cannot be greater than 255.

In Service

Check this to specify that the connection defined by this Sys62 is in service.

User ID

Specify a user ID to be associated with the connection. Mandatory if no sign-on takes place on the connection.

Language

Choose the national language in which messages are sent over the connection. You can choose English or Kanji.

Session Name

Specify the security name of the connection. Can be up to eight alphanumeric characters from the set A through Z, 0 through 9, $, @ and #.

Attach

Choose the level of security required when a user issues an attach request over this connection:

  • Identify - incoming attach requests must specify a user ID.
  • Verify - incoming attach requests must specify both a user ID and a password.
  • Persistent - the first attach request must specify both a user ID and a password, but subsequent attach requests require only a user ID.
  • Mixed - incoming attach requests can specify either Identify or Persistent.
  • Local - the authority of the user is taken to be that of the link.
Oper ID

Specify an operator ID used for routing messages. Specify this for a terminal that cannot be signed on, such as a printer. If you specify an operator ID for a terminal that can be signed on, it is overridden by the operator ID specified in the user's sign-on table entry. Up to three alphanumeric characters.

Oper Priority

Specify the operator priority for transactions run from this terminal. Specify this for a terminal that cannot be signed on, such as a printer. If you specify it for a terminal that can be signed on, it is overridden by the operator priority specified in the user's sign-on table entry. Defaults to 0(zero). Operator priority is one factor in determining a transaction's execution priority, which is the sum of:

  • Terminal priority
  • Transaction priority
  • Operator priority (this field)

The sum cannot be greater than 255.

Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - enables all the resource keys
  • Off - disables all the resource keys
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that security key.

Delete

Click this to delete this SysC. You only see this button if you have editing permissions for the group to which the SysC belongs.

Copy

Click this to create a new SysC that uses the values in this SysC.

Dump

Click this to create and view dump information for this SysC.

Parent topic: Pages for Viewing and Editing Resources


CICS T-Type - ttype_name (group_name)

Use this page to view and edit the T-type (terminal type definition) ttype_name. group_name indicates the group to which this T-type belongs.

The title bar gives details of the T-type you are editing and the resource group it belongs to.

Group List

Click this to display the CICS Group page group_name.

Apply

Click thtis 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 group in which the T-type resides.

Name

Shows the name for this T-type.

Description

Specify a description of the T-type. The text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.

Type

Choose the type of terminal device:

  • 3270 - A 3270 display device
  • Non-Facility - A non-physical device
  • Generic - Non-specific facility definition
  • ECI - External Call Interface dummy facility
  • System - A peer CICS or ES server
  • LU1-Printer or LU3-Printer - Printer device
  • Dialog Sys - Dialog System client facility
Shippable

Check this to indicate that this physical terminal definition may be shipped to a remote system in support of a transaction routing request. Ifa physical terminal definition is not marked shippable, then the target system must have the terminal explicitly defined as a remote terminal for the transaction routing request to succeed.

Map Size, Width

Specify the page width for the terminal type being defined. The width is defined as a number of columns, in the range 0 through 999. The default is 80.

Map Size, Height

Specify the page height for the terminal type being defined. The height is defined as a number of rows, in the range 0 through 999. The default is 24.

Alternate Map, Width

Specify the page size for the terminal type being defined, if you have specified an alternate screen size (non-default values for Alt Screen, Width and Alt Screen, Height). Alternate page size width is defined as a number of columns, in the range 0 through 999. The default is 80. Unexpected results may occur if the number of columns is not the same as the number of columns you specify for Alt Screen, Width. Defaults to the values specified in Map Size, Width.

Alternate Map, Height

Specify the page size for the terminal type being defined, if you have specified an alternate screen size (non-default values for Alt Screen, Width and Alt Screen, Height). Alternate page size height is defined as a number of rows, in the range 0 through 999. Unexpected results may occur if the number of columns is not the same as the number of columns you specify for Alt Screen, Height. Defaults to the values specified in Map Size, Height.

OB Oper ID, Yes

Check this to enable MSS to use the outbound operator identifiers to support the BMS routing facilities required by this terminal type definition.

Outboard Fmt, Yes

Check this to enable MSS BMS to delegate part of the presentation formatting to the client facility.

ASCII

Choose whether or not this terminal type has an ASCII feature:

No | The terminal type does not have an ASCII feature
7 Bit | Terminals of this type are ASCII-7 terminals. All outbound data is translated to 7-bit ASCII, and all inbound data is translated to EBCDIC
8 Bit | Terminals of this type are ASCII-8 terminals. All outbound data is translated to 8-bit ASCII, and all inbound data is translated to EBCDIC
Send Size

Specify the size, in bytes, of the receive buffer of a terminal of this type. This represents the maximum amount of data that the terminal can receive, and depends on the capability of the device. Considerations of line quality might lead you to specify a buffer size that is less than the terminal type's maximum buffer size. A message longer than the receive buffer is broken into as many request units as are necessary. Defaults to 0 (zero). If you specify a zero buffer size, the message is not broken up; the whole message is presented.

Receive Size

Specify the maximum size, in bytes, of a request unit that can satisfy a receive request. The value you specify may be rounded down.

Routed Msg

Indicates whether or not messages are routed to a terminal of this type by the EXEC CICS ROUTE command. Check this to indicate that BMS is to route to this terminal messages that are destined for all terminals, as well as messages destined for this terminal. If not checked, no messages are routed to this terminal, even if they are specifically destined for this terminal.

Logon Msg

Check this to specify that the logon transaction is initiated when a session is established and displays the logon message on the terminal. Automatic Transaction Initiation (ATI) is used to start the transaction, so you must check ATI. The transaction competes with any other ATI transactions for use of the terminal. If you check Lastline, the logon message does not overwrite any error message currently displayed.

Auto Connect

Check this to specify that a session is to be established with the terminal when the region starts up. Leave unchecked to specify that a session is to be established when the user signs on at the terminal.

ATI

Check this to enable a transaction to be automatically initiated on this terminal. If you leave this unchecked, you should check TTI to enable users to initiate transactions.

Create Sess

Check this to specify that a session can be initiated from a terminal of this type: EXEC START requests and Automatic Transaction Initiation (ATI) requests are allowed to create sessions automatically. Leave unchecked to specify that EXEC START requests and Automatic Transaction Initiation (ATI) requests are not allowed to create sessions automatically. Such requests are queued or rejected if a session has not been established.

TTI
Check this to enable users to initiate transactions at this terminal. If you leave this unchecked, you should check ATI to enable transactions to be automatically initiated.
NEP Class

Specify the transaction class of the node error program. Defaults to 0 (zero), which indicates that the default node error program is to be used.

Signoff
Choose which action is to be taken when GNTRAN (CESF or user-defined transaction) is attached and attempts to sign off the terminal. If you are using RACF 1.9 or later, specify the TIMEOUT limit in the RACF segment:
No | The terminal is not automatically signed off in the absence of user input.
Signoff | When the specified time has elapsed after the last input from the operator, the terminal is automatically signed off from CICS.
Signoff/Logoff When the specified time has elapsed after the last input from the operator, the terminal is automatically signed off from CICS and then logged off from VTAM. (This is not supported for TCAM-attached terminals.) LOGOFF is useful for an autoinstall model, because virtual storage is not wasted on entries for terminals that have been timed out. If GNTRAN fails to attach because of unprocessed data in the terminal buffer (resulting in a BID failure), the terminal will be signed off and logged off. GNTRAN will not run and will have no effect.
Note: You cannot change the value of this attribute when DEVICE(APPC) is specified. The default value in that case is SIGNOFF(NO).
Notify
Choose how the user is notified of system recovery. This option applies to the recovery of sessions for terminals in a CICS region running with either VTAM persistent sessions or with XRF. It is for use in situations where a terminal user may have to take action, such as sign on again, after a CICS restart:
None | The user is not notified.
Message | A message is displayed on the screen to say that the system has recovered. The message is specified in two BMS maps; DFHXRC1 and DFHXRC2 for XRF; and DFHXRC3 and DFHXRC4 for VTAM persistent sessions. These maps are in map set DFHXMSG. If reduced takeover time is important, use MESSAGE rather than TRANSACTION. The terminal must be capable of displaying BMS maps, and ATI.must be checked, to specify this option.
Transaction | A transaction is initiated at the terminal. The name of the transaction is specified by the RMTRAN system initialization parameter. (The default transaction for RMTRAN is the one specified in the GMTRAN system initialization parameter: the good-morning transaction.) If reduced takeover time is important, use MESSAGE rather than TRANSACTION. ATI must be checked to specify this option.
Option

Choose how MSS recovers the session and returns the terminal to normal service.

Sys Default | MSS selects the best recovery strategy based on session activity and the characteristics of the terminal.
Clear Receive | MSS sends a CLEAR request to reset the conversation state, or an UNBIND request if the session does not support the CLEAR request. MSS sends the CLEAR or UNBIND request only if the session was busy.
Release Sess | MSS sends an UNBIND request to clear the active session, if the session was busy.
Unconditional | MSS sends an UNBIND request to clear the active session, whether or not the session was busy.
None | The terminal session is not automatically recovered. If you checked Auto Connect, the terminal is automatically reconnected.
Last Line

Check this to specify that error messages are to be displayed at the bottom of the screen: If checked, an error message is displayed at the bottom of the screen, starting at a position that enables the entire message to be shown at once. If messages are received in quick succession, an earlier message might be overwritten before the user has time to read it. Messages displayed in this way may have the additional attributes specified by Intensify, Color and Highlight. If Last Line is not checked, an error message is displayed at the current cursor position, and without any additional attributes.

Intensify

Check this to have error messages displayed in an intensified field (bold). This only has an effect if Last Line is checked.

Color (Diagnostic Display)

Choose the color in which error messages are to be displayed on a terminal of this type. A setting other than No takes effect only if Last Line is checked.

Highlight (Diagnostic Display)

Choose the type of highlighting to be used for error messages displayed on a terminal of this type. A setting other than No takes effect only if Last Line is checked.

Def. Screen, Width

Specify the default screen width for the 3270 terminal type being defined. This is the screen width that is used when a transaction definition specifies a default screen. Screen width is defined as columns, in the range 0 through 999. The default is 80. There is no validity checking; incorrect sizes might lead to unpredictable behavior.

Def. Screen, Height

Specify the default screen height for the 3270 terminal type being defined. This is the screen height that is used when a transaction definition specifies a default screen. Screen height is defined as rows, in the range 0 through 999 The default is 24. There is no validity checking; incorrect sizes might lead to unpredictable behavior.

Alt. Screen, Width

Specify the alternate screen width for the 3270 terminal type being defined. This is the screen size that is used when a transaction definition specifies an alternate screen. Screen width is defined as columns, in the range 0 through 999. The default is 80. There is no validity checking; incorrect sizes might lead to unpredictable behavior.

Alt. Screen, Height

Specify the alternate screen height for the 3270 terminal type being defined. This is the screen size that is used when a transaction definition specifies an alternate screen. Screen height is defined as rows, in the range 0 through 999 The default is 24. There is no validity checking; incorrect sizes might lead to unpredictable behavior.

APL Keyboard

Check this to specify that the terminal type has the APL keyboard feature.

APL Text

Check this to specify that the terminal type can support the APL text character set.

Audible Alarm

Check this to specify that the terminal type has the audible alarm feature.

Color

Check this to specify that the terminal type has the color feature, which enables colors to be selected for individual fields.

Dual case kbd

Check this to specify that the terminal has a typewriter keyboard. Leave this unchecked to specify that the terminal has an operator console keyboard. Both types of keyboard transmit both upper-case and lower-case data.

Copy (Device Properties)

Check this to specify that the terminal type has the copy feature.

Extended DS

Check this to specify that the terminal type supports extensions to the 3270 data stream. You must check this if Color or Hilight are checked.

Highlight

Check this to specify that the terminal type has the extended highlight feature, enabling individual fields or characters to be displayed in bold, reverse video, or blinking.

Katakana

Check this to specify that the terminal type is a Katakana terminal. Katakana terminals do not support mixed case output. Upper-case characters appear as upper-case English, but lower-case characters appear as Katakana characters.

Light Pen

Check this to specify that the terminal type has the light pen selector feature. MSS emulates this feature using mouse clicks.

Form Feed

Check this to specify that the device has the form feed feature.

CGSCID

Specify the coded graphic character set global identifier (CGCSGID) that enables transaction programs to determine what character set is supported by this terminal. Defaults to 0,0, which means that the terminal type does not support this feature. The first field specifies the graphic character set global identifier (GCSGID), and the second field specifies the code page global identifier (CPGID).

Horizontal FF

Check this to specify that the device has the horizontal form feature. The devices that can use this feature are batch, batch data interchange, interactive, SCSPRT or LUTYPE4 logical units. If checked, BMS uses horizontal tabbing when formatting output documents. If unchecked, the HTAB option in the BMS map definition is ignored.

Vertical FF

Check this to specify that the device has the vertical form feature. The devices that can use this feature are batch, batch data interchange, interactive, SCSPRT or LUTYPE4 logical units. If checked, BMS uses vertical tabbing when formatting output documents. If unchecked, the VTAB option in the BMS map definition is ignored.

EWA Support

Check this to enable a 3270 device to shift its display into its alternate mode.

SOSI

Check this to specify that the terminal type supports mixed EBCDIC and DBCS fields.

PS

Check this to specify that the terminal type supports the programmed symbol facility. This facility enables you to use a maximum of six sets of 191 characters.

Outline

Check this to specify that the terminal type supports field outlining.

Numeric Lock

Check this to enable the numeric lock.

Buffer

Check this to specify that BMS buffers formatted data streams that are sent to a terminal of this type, that is, when an application issues a series of SEND TEXT PRINT commands, MSS sends a page to the terminal only when it is full. Leave thus unchecked to specify that when an application issues a series of SEND TEXT PRINT commands, MSS sends a page to the terminal for every command issued, filling up the page by appending blank lines if necessary.

Print Adapter

Check this to specify that output BMS screens with the PRINT option set on are copied automatically to an attached printer.

Transparency

Check this to enable background transparency.

Query

Check this to enable MSS to use the QUERY structured field to determine the characteristics of the device.

Text KB

Check this to specify that the 3270 device has the text-keyboard feature.

Mag Stripe Rdr

Check this to specify that the terminal type has the magnetic stripe reader feature. MSS emulates this feature using mouse clicks.

Validation

Check this:

  • For 8775 devices to enable the extended validation feature, which allows fields to be defined as TRIGGER, MANDATORY FILL, or MANDATORY ENTER.
  • For 3290 devices to enable the validation feature, which allows fields to be defined as MANDATORY FILL or MANDATORY ENTER.
Partition Support

Check this to enable the device to use partitions. This option is not valid for SCS printers.

Build Chain

Check this to specify that MSS is to reassemble request units into complete messages before passing data from a terminal of this type to a transaction program. Leave this unchecked to specify that messages are to be received by the transaction program in individual request units.

User Area

Specify the size, in bytes, of the user area of a terminal of this type. Defaults to 0 (zero).

In Shared Stg

Check this to force the user area into shared storage such hat it can be accessed by transactions that do not have this device as the primary facility.

Uppercase Trans

Choose how data entered in data entered in lower case is to be treated:

Yes | Data input in lower case is translated to upper case.
No | Data input in lower case is not translated to upper case.
Tranid | Transaction identifiers input in lower case are translated to upper case; not other input data is translated.
I/O Area

Specify the minimum and maximum sizes, in bytes, of the terminal I/O area to be passed to a transaction program when it issues a RECEIVE. If you enter a number in the first field, a terminal I/O area of at least that size is passed to the transaction program. If you specify values in both fields, and a message longer than that specified by the first field, but shorter than that specified by the second field is received, then a terminal I/O area of the maximum size is passed to the transaction program. A message longer than that specified by the second field causes the node abnormal condition program to send an exception response to the terminal. Defaults to 0,0. If you check ATI, you must specify a terminal I/O area of at least one byte.

Active, Display

Click this to display the currently installed definition of this resource.

Active, Install

Click this to install (make active) this resource.

Delete

Click this to delete this T-type. You only see this button if you have editing permissions for the group to which the T-type belongs.

Copy

Click this to create a new T-type, using the values set on this page as the basis for the new T-type.

Dump

Click this to create and view dump information for this T-type.

Parent topic: Pages for Viewing and Editing Resources


CICS Term - term_name (group_name)

Use this page to view and edit the Term term_name, selected from the CICS Group group_name page.

The title bar gives details of the Term you are editing and the resource group it belongs to.

Group List

Click this to display the CICS Group page group_name.

Apply

Click this to save changes you have made to the page, and refresh the page and add the new JCT to the group you specify in Grp. You see this button only if you have editing permissions for the group to which the FCT belongs.

Name

Shows the name for this Term.

Description

Specify the description for this Term.

Model

Choose whether or not this terminal definition can be used as a model terminal definition for autoinstall:

  • No - can be used only for a specific device that is not autoinstalled.
  • Yes - can be used as a model for autoinstall, as well as for a specific device that is not autoinstalled.
  • Only - can be used only as a model for autoinstall.
Model Name

Applicable only if Model is Yes or Only. Specify the name by which the definition is known to the Autoinstall Control Program. Specify a name of up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Defaults to the name of this Term.

Terminal Type

Specify the associated Typerterm definition, which must exist. Mandatory.

Net Name

Specify the terminal's network name. Mandatory if Model is Yes or No. Specify a name of up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. The first character must be a letter.

Remote Name

Specify the remote name. Applicable only for remote terminals. Necessary only if it differs from the local terminal name.

Remote SysID

Specify the remote system ID that holds the terminal definition. Applicable only for remote terminals. This must correspond to either:

  • The Local SYSID field in the SIT used to run the related remote MSS region.
  • The APPLID of another CICS system.
Transaction

Specify a transaction name. This specifies the only transaction that users can run from this terminal, apart from print and paging requests. Optional. If not specified, users can run any transaction from this terminal.

Priority

Specify the priority for transactions run from this terminal. Defaults to 0 (zero). Terminal priority is one factor in determining a transaction's execution priority, which is the sum of:

  • Terminal priority (this field)
  • Transaction priority
  • Operator priority

The sum cannot be greater than 255.

In Service

Check this to specify that this terminal is in service; that is, transactions can be initiated and messages sent.

Main Printer

Specify the printer used for handling print requests. This printer must be owned by the system that owns the terminal. The name can be up to four characters in length.

Prt. Copy

Check this to specify that the hardware copy feature (using the printer defined for this terminal) is used for print requests issued from this terminal.

Alternate Printer

Specify the printer used for handling print requests if the printer specified in Main Printer is unavailable. This printer must be owned by the system that owns the terminal. The name can be up to four characters in length.

Alt. Prt. Copy

Check this to specify that the hardware copy feature (using the alternate printer defined for this terminal) is to be used for print requests issued from this terminal.

User ID

Specify a user ID to be associated with the terminal. Mandatory if no sign-on takes place on the connection.

Language

Specify the national language in which messages are sent over the connection. You can select English or Kanji.

Session Name

Specify the security name of the terminal. Required only if the terminal is owned by a remote system and the connection method is APPC. Can be up to eight alphanumeric characters from the set A through Z, 0 through 9, $, @ and #.

Attach

Choose the level of security required when a user issues an attach request from this terminal:

  • Identify - incoming attach requests must specify a user ID
  • Verify - incoming attach requests must specify both a user ID and a password
  • Persistent - the first attach request must specify both a user ID and a password, but subsequent attach requests require only a user ID
  • Mixed - incoming attach requests may specify either Identify or Persistent
  • Local - the authority of the user is taken to be that of the link
Oper ID

Specify an operator ID to be used for routing messages. Specify this for a terminal that cannot be signed on, such as a printer. If you specify an operator ID for a terminal that can be signed on, it is overridden by the operator ID specified in the user's sign-on table entry. Up to three alphanumeric characters.

Oper Priority

Specify the operator priority for transactions run from this terminal. Specify this for a terminal that cannot be signed on, such as a printer. If you specify it for a terminal that can be signed on, it is overridden by the operator priority specified in the user's sign-on table entry. Defaults to 0 (zero). Operator priority is one factor in determining a transaction's execution priority, which is the sum of:

  • Terminal priority
  • Transaction priority
  • Operator priority (this field)

The sum cannot be greater than 255.

Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - enables all the resource keys
  • Off - disables all the resource keys
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Active, Display

Click this to display the currently installed definition of this resource.

Active, Install

Click this to install (make active) this resource.

Delete

Click this to delete this Term. You see this button only if you have editing permission for the group to which the Term belongs.

Copy

Click this to create a new Term using the entries specified on this page.

Dump

Click this to create and view dump information for this Term.

Parent topic: Pages for Viewing and Editing Resources


CICS TST - tst_name (group_name)

Use this page to view and edit the TST pct_name, selected from the CICS Group group_name page.

The title bar gives details of the TST you are editing and the resource group it belongs to.

Group List

Click this to display the CICS Group page group_name.

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 group in which the TST resides.

Name

Shows the name for the TST.

Description

Specify a description for the TST (can be up to 60 characters).

Recoverable

Check this to enable recovery of the temporary storage queue in the event of an abnormal termination of either MSS or the transaction processing the destination.

Name (Remote Queue)

Specify the name of a temporary storage queue.

SYSID

Specify the system or region in which the temporary storage queue resides. The name specified must be the same as that given in Name in the SysC or Sys62 definition.

Resource Keys, all

Choose a setting to apply to all the resource keys:

  • On - enables all the resource keys
  • Off - disables all the resource keys
Resource Keys, 1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Security Keys, all

Choose a setting to apply to all the security keys:

  • On - enables all the security keys
  • Off- disables all the security keys
Security Keys, 1 - 64

Check any of the boxes 1 through 64 to activate that security key.

Delete

Click this to delete this TST. You only see this button if you have editing permissions for the group to which the TST belongs.

Copy

Click this to create a new TST using the entries specified on this page.

Dump

Click this to create and view dump information for this TST.

Parent topic: Pages for Viewing and Editing Resources


CICS XAT - xat_name (group_name)

Use this page to view and, if you have the required permissions, edit the XAT xat_name, selected from the CICS Group group_name page. An XAT is an XA-compliant database table.

The title bar gives details of the XAT you are editing and the resource group it belongs to.

Group List

Click this to display the CICS Group page group_name.

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 group in which the XAT resides.

Name

Shows the name of this XAT.

Description

Specify a description of the XAT. Acceptable characters are A through Z, 0 through 9, $, @ and #.

Switch Module

Specify the location of the executable file (.dll) that contains the entry point that returns the xa_switch_t structure to the enterprise server.

DB Name

Specify the name by which the resource manager is known.

User ID

Specify a resource manager ID, used internally to identify a particular XA configuration. This must be unique within the enterprise server.

Password

Specify the password required for the User ID. If you are entering a new password, you have to confirm it by entering it in PW Verify.

PW Verify

Specify the password again, if you are creating a new password, to verify you have entered it correctly.

Open String, Free Format

Specify 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, Free Format

Specify 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.

Load Module

Choose an external resource manager that the server needs to communicate with on behalf of container-managed applications.

Load Module, Name

if you chose User in Load Module, specify the name of the module that supplies the run-time support for the database calls made by the application.

Delete

Click this to delete this XAT. You see this button only if you have editing permissions for the group to which the XAT belongs.

Copy

Click this to create a new XAT using the entries specified on this page.

Dump

Click this to create and view dump information for this XAT.

Parent topic: Pages for Viewing and Editing Resources


CICS URIMAP - urimap_name (group_name)

Use this page to view and edit the URIMAP urimap_name, selected from the CICS Group group_name page.

Click Apply to save changes you have made to the page and refresh the page.

Name
The name of this URIMAP definition. If you click Apply, the message Update complete is also displayed when the changes you have made to the URIMAP have been saved and the entry updated. Click Refresh to remove this message.
Description
A description of this URIMAP definition.
Status
Specifies whether this URIMAP definition is installed in an enabled or disabled state.
Usage
Specifies whether this URIMAP definition is for:
  • CICS as an HTTP server
  • CICS as an HTTP client
Universal Resource Identifier:
Scheme
The scheme component of the URI.
Port
The number of the port used by the user application when it communicates with a server.
Host
The host name, or IPv4 or IPv6 address, of the URI.
Path
The path component of the URI.
Associated CICS Resources:
TCPIPService
The name of a TCPIPSERVICE resource definition that defines an inbound port.
Analyzer
Indicates whether an analyzer program is used in processing the HTTP request.
Converter
The name of a converter program used to convert (or perform other processing) on the request and response.
Transaction
The name of an alias transaction used either to run the user application that composes the HTTP response, or to start the pipeline.
Program
The name of the user application program that composes the HTTP response.
Pipeline
Not supported for this release.
WebService
Not supported for this release.
Security Attributes:
Ciphers
A string of up to 56 hexadecimal digits that is interpreted as a list of up to 28 2-digit cipher suite codes.
Certificate
The label of the X.509 certificate that is used as the SSL client certificate during the SSL handshake.
Authenticate
Specifies whether to send basic authentication information in the HTTP response.
Static Document Properties:
Not supported for this release.
Redirection:
Not supported for this release.
Parent topic: Pages for Viewing and Editing Resources


CICS TCPIPSERVICE - tcpipservice_name (group_name)

Use this page to view and edit a the TCPIPSERVICE tcpservice_name, selected from the CICS Group group_name page.

Click Apply to save changes you make to the page, and refresh the page.

Name
The name of this TCPIPSERVICE definition. If you click Apply, the message "Update complete" is also displayed when the changes you have made to the definition have been saved and the entry updated. Click Refresh to remove this message.
Description
A description of this definition.
URM
The name of a user-replaceable program that this service invokes.
Port No
The number of the port on which CICS listens for incoming client requests.
Status
Specifies the initial status of the service after installation, either OPEN if CICS is to begin listening for this service after installation, or CLOSE if not.
Protocol
The application level protocol used on the TCP/IP port.
Transaction
The ID of the CICS transaction to process new requests that this service receives.
Backlog
Not supported for this release.
TSQ Prefix
A code to identify items in the temporary storage queue (TSQ).
IP Address
Not supported for this release.
Socket Close
Not supported for this release.
Max Data Length
Not supported for this release.
Security:
Not supported for this release.
DNS Connection Balancing:
Not supported for this release.
Parent topic: Pages for Viewing and Editing Resources


CICS DOCTEMPLATE - doctemplate_name (group_name)

Use this page to view and edit the DOCTEMPLATE doctemplate_name, selected from the CICS Group group_name page.

Click Add to save changes you have made to the page, refresh the page and add the new template to the group you specify in Grp. When you click Add, the button changes to Apply.

Name
The name of this template.
Grp
The group to which this resource belongs. Do not use group names beginning with "DFH" as these are reserved for use by CICS.
Description
A description of this template. This can be up to 58 characters long.
Append CR/LF
Specifies whether CICS deletes trailing spaces from, and appends carriage return/line feed to, each logical record of the template.
Content Type
The format of the template contents, either BINARY or EBCDIC. If you choose BINARY, when the template is loaded its contents are not parsed; if you select EBCDIC, the template contents are parsed as EBCDIC text.
Template Name
The name by which the template is know to application programs that use it. The name can be up to 48 characters long. If you do not enter a value, it defaults to the value of Name.
Template Type
The type for the source of the template.
Enter details for one of the following:
File
The name of a CICS file which contains the template. This name can be up to eight characters long.
TS Queue
The name of a temporary storage queue containing the template. This name can be up to 16 characters long.
TD Queue
The name of a transient storage queue containing the template. This name can be up to four characters long.
Program
The name of the CICS program that contains the template. This name can be up to 48 characters long. If you do not specify a value, the template name is used.
Exit Program
The name of the exit program that generates this template. This name can be up to eight characters long.
MVS PDS
The details of an MVS partitioned data set (PDS) containing the template.
  • DD Name, the name of the PDS. This name can be up to eight characters long. The default is "DFHHTML".
  • Member Name, the name of a member in the PDS. This name can be up to eight characters long.
HFS File
The name of a z/OS UNIX System Services file containing the template. This can be either the absolute name including all directories and beginning with a slash, or a name relative to the home directory of the CICS region. The name can be up to 255 characters long.
Parent topic: Pages for Viewing and Editing Resources


CICS TRANCLASS trnclass_name (group_name)

Use this page to view and edit the TRANCLASS trnclass_name, selected from the CICS Group group_name or CICS Startup List startup_list page.

The title bar gives details of the TRANCLASS you are editing and the resource group it belongs to.

Group List

Click this to display the CICS Group page group_name.

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 group in which the TRANCLASS resides.

Name

Shows the name of this TRANCLASS.

Description

A description of the transaction program (can be up to 60 characters).

MaxActive

Specify the maximum number of transactions in this transaction class that are allowed to be active, in the range 0 through 999.

PurgeThresh

Purge threshold defines a limit to the number of transactions queuing for this transaction class. After this limit is reached, transactions are purged. Specify a threshold:

  • NO - no limit
  • number - purge threshold number (1 - 1000000)
Note: Not currently supported.
Install

Click this to install and make this resource active.

Delete

Click this to delete this TRANCLASS. You only see this button if you have editing permissions for the group to which the TRANCLASS belongs.

Copy

Click this to create a new TRANCLASS that uses the values in this one.

Dump

Click this to create and view dump information for this TRANCLASS.

Parent topic: Pages for Viewing and Editing Resources


CICS PIPELINE - pipeline_name (group_name)

Use this page to view and edit the PIPELINE pipeline_name, selected from the CICS Group group_name page.

Click Apply to save changes you have made to the page and refresh the page.

Name

Shows the name of this PIPELINE definition. If you click Apply, the message Update complete is also displayed when the changes you have made to the PIPELINE have been saved and the entry updated. Click Refresh to remove this message.

Description

Specify a description of the transaction program (can be up to 60 characters).

Status
Choose a status for the PIPELINE:
  • Enabled - enables this PIPELINE.
  • Disabled - disables the PIPELINE.
Resp Wait
  • DEFT - indicates the default value of the transport protocol. HTTP is 10 seconds. MQ is 60 seconds.
  • 0-9999 - the number of seconds that an application should wait for a response message from the service.
Config File
Shows the fully qualified pipeline configuration file.
Shelf
Must reference a valid directory, but currently unused.
WebSvc Dir
Shows the fully qualified name of the web service binding directory. When the PIPELINE is installed, this directory is scanned for .wsbind files and a WEBSERVICE resource is created and installed for each file found.
Parent topic: Pages for Viewing and Editing Resources


CICS WEBSERVICE - webservice_name (group_name)

Use this page to view and edit the WEBSERVICE webservice_name, selected from the CICS Group group_name page.

Click Apply to save changes you have made to the page and refresh the page.

Name

The name of this WEBSERVICE definition. If you click Apply, the message Update complete is also displayed when the changes you have made to the WEBSERVICE have been saved and the entry updated. Click Refresh to remove this message.

Description

Specify a description of this WEBSERVICE definition.

Validation

Specifies whether validation of SOAP messages against the associated schema will be performed. This is not currently supported and so only ‘No’ is a valid option.

Pipeline

Shows the name of the PIPELINE associated with this WEBSERVICE.

WSBind

Shows the fully qualified location of the web service binding file.

WSDL File

Shows the fully qualified location of the WSDL file (currently unused).

Archive File

Unused.

Parent topic: Pages for Viewing and Editing Resources


Users

  • Users List
  • Create a New CICS SNT
  • View and Edit a CICS SNT
Parent topic: Enterprise Server Monitor and Control (ESMAC)


Users List

Use this page to view the users defined for this server.

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


Create a New CICS SNT

Use this page to create a new user for ESMAC.

If you displayed this page by clicking Copy on a previous page, the values on the previous page are used as the basis for the new SNT.

If you displayed this page by clicking New on a previous page, some values on this page are already set to default values.

Add

Click this to save changes you have made to the page, refresh the page, and add the user.

Name

Specify the user's name.

Description

Specify a short description of this SNT.

Password

Specify a password for this user. The maximum number of characters is 8.

Repeat PW

Respecify the password to ensure that it has been entered correctly.

Upper Case

Check this to force the password into upper case.

Remove PW
Check this to remove the password from the resource definition file. If no password is specified the user does not require a password.
Operator ID

Specify an operator ID. This is a three-character code that identifies the user to applications.

Priority

Specify the operator priority for transactions. Defaults to 0 (zero). Operator priority is one factor in determining a transaction's execution priority, which is the sum of:

  • Terminal priority
  • Transaction priority
  • Operator priority (this field)

The sum cannot be greater than 255.

Timeout

Specify the maximum interval in minutes since the last activity of an ESMAC or TN3270 client before the user ID is automatically logged off. The default value is 0, meaning no timeout. This value overrides ID Timeout on the SIT page.

Note: Terminal timeouts (SIT parameter or user ID parameter) must be less than 16 hours.
Group Prefix

Do not use. The group prefix is a Mainframe Express feature that gives developers control over resource groups with a specific name prefix.

Oper Class

Specify a value for the operator class, which is normally used for message routing but can be used for any user/application relationship.

Resource Keys
all
Choose a setting to apply to all the resource keys:
  • On - enables all the resource keys
  • Off - disables all the resource keys
1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Security Keys
all
Choose a setting to apply to all the resource keys:
  • On - enables all the security keys
  • Off - disables all the security keys
1 - 64
Check any of the boxes 1 through 64 to activate that security key.
Surrogate Keys
all
Choose a setting to apply to all the surrogate keys:
  • On - enables all the surrogate keys
  • Off - disables all the surrogate keys
1 - 24

Check any of the boxes 1 through 24 to activate that surrogate key.

JCL Submit

Check this to enable this user to submit JCL jobs via the cassub utility.

ES Security

Check this for the user ID mfuser to enable ESMAC security.

ESMAC Access
Master Flag

Check this to enable the user to access the main ESMAC screens. If unchecked, the user will only be able to view summary server information and environment variables.

all
Choose a setting for the level of access the user will have to all types of resource:
  • Rd - sets all items to read access
  • Upd - sets all items to update access
  • No - denies access for all items
JES - XAT

Choose what type of access this user can have to a resource of this type:

  • Rd - sets the item to read access
  • Upd - sets the item to update access
  • No - sets the item to no access
Parent topic: Users


View and Edit a CICS SNT

Use this page to view information about the SNT you selected from the Users page. You can view information about the SNT, and change various parameters of the SNT.

Apply

Click this to save changes you have made to the page and refresh the page. You see this button only if you have permission to edit the SNT.

Name

Shows the name for this SNT.

Description

Specify a short description for this SNT.

Password

Specify the password for this user. The maximum number of characters is 8.

Repeat PW

Specify the password again, if you are changing the password, to ensure that it has been entered correctly.

Upper Case

Check this to force the password into upper case.

Operator ID

Specify an operator ID. This is a three-character code that identifies the user to applications.

Priority

Specify the operator priority for transactions. Defaults to 0 (zero). Operator priority is one factor in determining a transaction's execution priority, which is the sum of:

  • Terminal priority
  • Transaction priority
  • Operator priority (this field)

The sum cannot be greater than 255.

Timeout

Specify the maximum interval in minutes since the last activity of an ESMAC or TN3270 client before the user ID is automatically logged off. The default value is 0, meaning no timeout. This value overrides ID Timeout on the SIT page.

Note: Note that Terminal timeouts (SIT parameter or user ID parameter) must be less than 16 hours.
Group Prefix

Do not use. The group prefix is an Mainframe Express feature that gives developers control over resource groups with a specific name prefix.

Oper Class

Specify a value for the operator class, which is normally used for message routing but can be used for any user/application relationship.

Resource Keys
all
Choose a setting to apply to all the resource keys:
  • On - enables all the resource keys
  • Off - disables all the resource keys
1 - 24

Check any of the boxes 1 through 24 to activate that resource key.

Security Keys
all
Choose a setting to apply to all the resource keys:
  • On - enables all the security keys
  • Off - disables all the security keys
1 - 64
Check any of the boxes 1 through 64 to activate that security key.
Surrogate Keys
all
Choose a setting to apply to all the surrogate keys:
  • On - enables all the surrogate keys
  • Off - disables all the surrogate keys
1 - 24

Check any of the boxes 1 through 24 to activate that surrogate key.

JCL Submit

Check this to enable this user to submit JCL jobs via the cassub utility.

ES Security

Check this for the user ID mfuser to enable ESMAC security.

ESMAC Access
Master Flag

Check this to enable the user to access the main ESMAC screens. If unchecked, the user will only be able to view summary server information and environment variables.

all
Choose a setting for the level of access the user will have to all types of resource:
  • Rd - sets all items to read access
  • Upd - sets all items to update access
  • No - denies access for all items
JES - XAT

Choose what type of access this user can have to a resource of this type:

  • Rd - sets the item to read access
  • Upd - sets the item to update access
  • No - sets the item to no access
Delete

Click this to delete this SNT. You only see this button if you have editing permissions for the SNT.

Copy

Click this to create a new SNT using the entries specified on this page.

Dump

Click this to create and view dump information for this SNT.

Parent topic: Users


Env.Vars.

Use this page to view information about the environment variables used by this server.

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.Debug

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.

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.

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.

See the environment variable ES_DISABLE_DFLTUSR_SIGNON in Environment variables in alphabetical order for details about how to control the default user sign on.

Parent topic: Enterprise Server Monitor and Control (ESMAC)


Listeners

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
TN3270 | To list service listeners for TN3270 clients (MSS only)
MSS ISC | To list service listeners for MSS Intersystem Communication
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

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
Check this to enable the Secure Sockets Layer (SSL) which provides encrypted communication between server and client applications and authentication of online entities.
Certificate
Specify the filename of your server certificate - for example, srvcert.pem.

The server certificate proves your identity to people you communicate with online and enables them to send you data in encrypted form. If the server certificate file is not in the default directory (which is the certs directory in the location defined by the SSLDIR environment variable), you must also specify the full path to the file.

Keyfile
Specify the filename of your private key file - for example, srvkey.pem. The private key is used to decrypt encrypted data you receive.

If this file is not in the default directory (which is the keys directory in the location defined by the SSLDIR environment variable), you must also specify the full path to the file.

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.
  • TN3270 for client requests for CICS transations that use the TN3270 protocol. You can only use TN3270 listeners with Mainframe Subsystem Support.
  • MSS ISC for client requests from non-CICS programs for CICS transactions. You can only use MSS Inter System Communications listeners with Mainframe Subsystem Support.
  • 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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.

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

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

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 LDAP Security Manager from the Enterprise Server UI


MF Directory Server Users, Add or Edit

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.

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.

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

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.

This parameter is currently ignored by the ESM Module.

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.

This parameter is currently ignored by the ESM Module.

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin.

Name

Specify the name used to identify the security manager.

Parent topic: Security Configuration Screen Help


Add to Default ES Security Manager List

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

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

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.

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.

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.

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.

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

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

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.

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.

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.

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

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin.

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.

This parameter is currently ignored by the ESM Module.
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.

This parameter is currently ignored by the ESM Module.

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

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

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

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.

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.

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).

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.

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).

Security Facility Configuration

The Security Facility Configuration parameters are available on this screen only when MFDS is configured to use an ESF (i.e. set up to use a Security Manager other than "MFDS Internal Security"). Otherwise no ESF security configuration options (including the caching options) will be seen on this MFDS Security tab screen:

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.

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.

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.

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


Remove Security Manager Reference Confirmation

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

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.

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

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.

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.

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.

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

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin.

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

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.
  • About Modernized Applications
  • Managing Resources
  • Adding and Deleting Services
  • Configuring and Monitoring Services
  • Configuring Implementation Packages
  • Deploying EJBs and Resource Adapters
Parent topic: Enterprise Server


About Modernized Applications

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

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

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

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

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

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

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.

A CICS EXCI call can only be executed in a service that is Container Managed. An EXCI call executed in an Application Managed generates an abend: EXIA

Parent topic: Managing Resources


Container-managed Services

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.

CAUTION:
A CICS EXCI call can only be executed in a service that is Container Managed. An EXCI call executed in an Application Managed generates an abend: EXIA
Parent topic: Managing Resources


Mixing Container-managed and Application-managed Services

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

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

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

  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

  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

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

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

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

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

  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

  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

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

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

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

  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 %SYSTEMDRIVE%\Documents and Settings\user-ID\My Documents\Micro Focus\<product name> X.X\WORKAREA\es-name where es-name is the name of the enterprise server and user-ID is the user account that is running it. 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).

If you are running the Directory Server as a service that logs on as the Local System account (LocalService), any Enterprise Server that it starts will also run under that account. Hence, the location of the files will typically be C:\Documents and Settings\LocalService\My Documents\Micro Focus\<product name> X.X\WORKAREA\es-name. By default, Windows hides the LocalService subdirectory of Documents and Settings. In order to view this directory, you must configure your Windows Explorer so that: Show hidden files and folders is set, and Hide protected operating system files is not set.

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

  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

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

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

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

  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 .dll
  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.
Note: For each service execution, COBPATH is changed dynamically based on the path of the associated package. Idle SEPs inherit their COBPATH setting from the environment or from the configuration of the enterprise server. There are various tools that enable you to verify this depending on the OS.

The execution of a service overrides COBPATH for the duration of that service after which the value of COBPATH is restored.

The value of COBPATH is not displayed on the Environment Space page within ESMAC (to display the page, click ES Monitor & Control in the details of the running server and then click Env.Vars.). This is because ESMAC is a service and is subject to these same rules but has no configurable package.

Parent topic: Configuring Packages
Parent topic: Work with Packages
Related information
To Add a Service to an Enterprise Server Instance


To Delete a Package

  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

  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

  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

  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

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Server\bin . 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

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.
  • MFRHJSON - handles REST requests that use JSON content bodies.
  • The Request Handlers Table
  • Configuring Handlers
Parent topic: Configuring Implementation Packages


The Request Handlers Table

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

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

  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

  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

  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

  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

  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

  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 EJBs and Resource Adapters

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 Java application server, such as WebSphere or WebLogic.

Resource adapters enable EJBs deployed on Java application servers to communicate with COBOL on an enterprise server. Resource adapters are also known loosely as J2EE or Java EE 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

Java EE clients run in a Java EE application server such as IBM WebSphere or Oracle WebLogic. When a service is processing requests from a Java EE client, the Java EE 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 Java EE application server, whether the COBOL service is container-managed or application-managed.

Parent topic: Deploying EJBs and Resource Adapters


Deploying EJBs Overview

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 Java EE 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 Java EE 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 Java EE 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 Java EE application server with an enterprise server. Resource adapters are also known as Java EE connectors and they are packaged in resource archive (.rar) files.

Many Java EE 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

Deploying EJBs involves configuring them in the third party Java application server, 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 necessary 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

  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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\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\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 Java EE Application Servers


To Create an .ear File for your EJB

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 Java EE Application Servers


To Deploy to WebLogic

  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 Enterprise Developeror Enterprise 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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin and \bin64 of your COBOL system installation.
    • mfconnector.jar - This is by default in a subdirectory under %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\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.cmd , and is located in your domain directory of your WebLogic installation.
  4. Go to the end of the file.
  5. Above the line @rem Call WebLogic Server , add the following lines:
    set java_home=jdk_path
set mf_home=mfcobolpure_path
set classpath=%java_home%\lib\tools.jar;
              %mf_home%\mfconnector_path\mfconnector.jar;
              %mf_home%\mfcobolpure.jar

    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
%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\javaee\javaee5\oracleweblogic10
Java EE 6, WebLogic 1211
%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\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. Go to the Start menu for WebLogic and choose the domain and server that you specified in your startup script. This Start menu item runs the startup script.

    You cannot start WebLogic using Services in Windows Control Panel and you cannot configure it in Control Panel to start automatically when you reboot the machine.

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 Enterprise Developeror Enterprise 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 Java EE Application Servers


To Deploy to WebSphere

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

Either start the server from the Start menu, or run the startup script by entering the following command from the bin directory of your WebSphere installation:

startserver 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 Java EE Application Servers


To Deploy to JBoss

Installing JBoss Application Server

You can download JBoss Application Server from http://jbossas.jboss.org/downloads, 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

For JBoss 5.1 and 6.1, the JBoss Application Server provides deployment descriptors. The deployment descriptors require some changes before generating EJBs. These changes are described below, in which your JBoss installation directory is the top-level directory of your JBoss installation.

JBoss 5.1
Using any text editor, edit the following JBoss files as specified here:
run.bat
Located in your JBoss installation's bin directory.

Insert a SET statement to set the JAVA_HOME environment variable to the directory containing your JDK. For example:

set JAVA_HOME=c:\program files\java\jdk1.6

jboss-service.xml
Located in your JBoss installation's server\default\conf directory.

Set the callByValue attribute to true:

<attribute name="callByValue">true</attribute>

war-deployers-jboss-beans.xml
Located in your JBoss installation's server\default\deployers\jbossweb.deployer\META-INF directory.

Set the java2ClassLoadingCompliance property to true:

<property name="java2ClassLoadingCompliance">true</property>

ear-deployer-jboss-beans.xml
Located in your JBoss installation's server\default\deployers directory.

Set the isolated property to false:

<property name="isolated">false</property>

Set the callByValue property to true:

<property name="callByValue">true</property>

jboss-ra.xml (optional)
Included in the mfcobol-notx.rar archive file located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\javaee\javaee5\jboss5 directory.

To enable tracing, set the trace attribute to true:

<attribute name="trace">true</attribute>

JBoss 6.1
Using any text editor, edit the following JBoss files as specified here:
naming-jboss-beans.xml
Located in your JBoss installation's server\default\deploy directory.

Set the callByValue property to true:

<property name="callByValue">true</property>

ear-deployer-jboss-beans.xml
Located in your JBoss installation's server\default\deployers directory.

Set the isolated property to false:

<property name="isolated">false</property>

Set the callByValue property to true:

<property name="callByValue">true</property>

ejb-deployer-jboss-beans.xml
Located in your JBoss installation's server\default\deployers directory.

Set the callByValue property to true:

<property name="callByValue">true</property>

war-deployers-jboss-beans.xml
Located in your JBoss installation's server\default\deployers\jbossweb.deployer\META-INF directory.

Set the java2ClassLoadingCompliance property to true:

<property name="java2ClassLoadingCompliance">true</property>

jboss-ra.xml (optional)
Included in the mfcobol-notx.rar archive file located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\javaee\javaee6\jboss6 directory.

To enable tracing, set the trace attribute to true:

<attribute name="trace">true</attribute>

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.

JBoss 5.1 and 6.1
  • Run jboss_home\bin\run.bat to start it.
  • Run jboss_home\bin\shutdown.bat -S to stop it.
JBoss 7.1
  • Run jboss_home\bin\standalone.bat to start it.
  • Run jboss_home\bin\jboss-cli --connect command=:shutdown to stop it.

Deploying the Resource Adapter

JBoss 5.1 and 6.1

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 descriptor 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 by default is 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.
JBoss 7.1
To deploy a resource adapter for JBoss 7.1, update the standalone.xml file, located in your JBoss installation's standalone\configuration directory, as follows:
<subsystem xmlns="urn:jboss:domain:jca:1.1"> element
Edit the <archive-validation>, child of the <subsystem xmlns="urn:jboss:domain:jca:1.1"> element, to disable it:

<archive-validation enabled="false" fail-on-error="true" fail-on-warn="false"/>

Add the mfcobol-notx.rar resource adapter
As a child of <profile>, add the following <subsystem> to standalone.xml:
<subsystem xmlns="urn:jboss:domain:resource-adapters:1.0">
    <resource-adapters>
        <resource-adapter>
            <archive>mfcobol-notx.rar</archive>
            <transaction-support>NoTransaction</transaction-support>
            <connection-definitions>
                <connection-definition class-name="com.microfocus.cobol.connector.spi.CobolNoTxManagedConnectionFactory" jndi-name="java:/eis/MFCobol_v1.5" pool-name="CobolConnectionFactory">
                    <pool>
                        <min-pool-size>2</min-pool-size>
                        <max-pool-size>10</max-pool-size>
                    </pool>
                    <security>
                        <application/>
                    </security>
                </connection-definition>
            </connection-definitions>
        </resource-adapter>
    </resource-adapters>
</subsystem>
Add the mfcobol-localtx.rar resource adapter
As a child of <profile>, add the following <subsystem> to standalone.xml:
<subsystem xmlns="urn:jboss:domain:resource-adapters:1.0">
    <resource-adapters>
        <resource-adapter>
            <archive>mfcobol-localtx.rar</archive>
            <transaction-support>LocalTransaction</transaction-support>
            <connection-definitions>
                <connection-definition class-name="com.microfocus.cobol.connector.spi.CobolLocalTxManagedConnectionFactory" jndi-name="java:/eis/MFCobol_v1.5" pool-name="CobolConnectionFactory">
                    <pool>
                        <min-pool-size>2</min-pool-size>
                        <max-pool-size>10</max-pool-size>
                    </pool>
                    <security>
                        <application/>
                    </security>
                </connection-definition>
            </connection-definitions>
        </resource-adapter>
    </resource-adapters>
</subsystem>
Add the mfcobol-xa.rar resource adapter
As a child of <profile>, add the following <subsystem> to standalone.xml:
<subsystem xmlns="urn:jboss:domain:resource-adapters:1.0">
    <resource-adapters>
        <resource-adapter>
            <archive>mfcobol-xa.rar</archive>
            <transaction-support>XATransaction</transaction-support>
            <connection-definitions>
                <connection-definition class-name="com.microfocus.cobol.connector.spi.CobolManagedConnectionFactory" jndi-name="java:/eis/MFCobol_v1.5" pool-name="CobolConnectionFactory">
                    <xa-pool>
                        <min-pool-size>2</min-pool-size>
                        <max-pool-size>10</max-pool-size>
                    </xa-pool>
                    <security>
                        <application/>
                    </security>
                </connection-definition>
            </connection-definitions>
        </resource-adapter>
    </resource-adapters>
</subsystem>

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.

JBoss 5.1 and 6.1
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
JBoss 7.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\standalone\deployments

Logging

JBoss 5.1 and 6.1
JBoss stores log files and traces by default in jboss_home\server\default\log\server.log.
JBoss 7.1
JBoss stores log files and traces by default in jboss_home\standalone\log\server.log.

Configuring a JDBC Data Source for XA Transactions

If the application being deployed connects to a third-party database, you need to configure a JDBC data source and specify information such as the JNDI name of the data source.

JBoss 5.1 and 6.1
For an Oracle database, edit the Oracle-supplied deployment descriptor oracle-xa-ds.xml.
JBoss 7.1
Add a data source to the standalone.xml file.

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 Java EE Application Servers


Resource Adapters Supplied by Micro Focus

The Micro Focus resource adapters enable EJBs deployed on Java application servers to communicate with COBOL on an enterprise server. Resource adapters are also known loosely as J2EE or Java EE connectors.

Before an EJB can communicate with the COBOL code running on an enterprise server, you need to:

  • Deploy a resource adapter to the Java 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 or Java EE version it uses. The following resource adapters are supplied for each supported application server and Java 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 Java 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 Java 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 Java application server
Deployment Descriptors that Are Required


To Add Support for Micro Focus Resource Adapters

  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:

    set classpath=%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin\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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\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 Java EE Application Servers


To Deploy a Micro Focus Resource Adapter to a Java Application Server

  1. Start your Java 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 Enterprise Server or Enterprise Developer 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 Java version. They are available in the application server subdirectories under %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\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 Java 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 Java EE Application Servers


Deployment Descriptors that Are Required

Deployment descriptors are xml files that describe the component to be deployed. Java 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 Enterprise Developer, generic deployment descriptors are created and they are packaged into the relevant archive files. Some Java 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
Related reference
EJB Troubleshooting
To create deployment descriptors manually


To Create Deployment Descriptors Manually

You can create deployment descriptors using the administration tool provided by your Java 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 Java 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 Java EE Application Servers
Related information
EJBs and Resource Adapters


CustomRecord and the RuntimeProperties Support

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

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 EJBs 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 tasks
To Deploy a Micro Focus Resource Adapter to a Java 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

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 %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\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.
  • For WebSphere application servers, is the trace property for your mfcobol-notx.rar resource adapter set to true? If it is, then you can find trace information written to the WebSphere log file. For information on configuring resource adapters in WebSphere, and for the location and contents of the WebSphere log file, see your IBM WebSphere documentation.
  • For JBOSS and WebLogic application servers, is the trace parameter in the ra.xml file set to true? If so, you can find trace information in the JBOSS or WebLogic log file respectively. For information on editing the ra.xml file, see Deployment Descriptors that Are Required . See your JBOSS or WebLogic documentation for further details with regard to the log file.
  • Was any information written to the communications server log file log.html? See Communications Server Log Files for more information.
  • 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 Java 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 Java application server


Enterprise Server Task Index

  • Accessing the Enterprise Server Administration UI
  • Accessing the ESMAC User Interface
  • Administer a Server Using ESMAC
  • Configure the Directory Server
  • Deploy to Java EE Application Servers
  • Log On and Off
  • Monitor Directory Server
  • Monitor and Manage Enterprise 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
  • Work with WebSphere MQ
  • CICS Support Tasks
  • IMS Support Tasks
  • JCL Support Tasks
Parent topic: Enterprise Server


Accessing the ESMAC User Interface

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

  • 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 Reply to an ACCEPT FROM CONSOLE Statement
  • To Shut Down a Server from ESMAC
  • 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

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

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 an associated JCL is looping, or if it 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


Configure the Directory Server

  • To Configure the MF Directory Server
Parent topic: Enterprise Server Task Index


To Configure the MF Directory Server

  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


Deploy to Java EE Application Servers

  • 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 Java Application Server
Parent topic: Enterprise Server Task Index


Log On and Off

  • To Log On to Enterprise Server Administration
  • To Log Off from Enterprise Server Administration
Parent topic: Enterprise Server Task Index


Monitor Directory Server

  • 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


Monitor and Manage Enterprise Server

  • To View Server Instances and Properties in Operations Manager
  • To import Server Management Packs into Operations Manager
  • To Use Performance Counters
  • To Enable Performance Counters
  • To Use Windows Event Logging
  • To Enable Windows Event Logging
Parent topic: Enterprise Server Task Index


Start and Stop the Directory Server

  • To Start the Directory Server
  • To Start the Directory Server from the Command Line
  • To Stop the Directory Server
  • To stop the Directory Server when not running as a service
Parent topic: Enterprise Server Task Index


Work with Communication Processes and Service Listeners

  • 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

  • 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

  • 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

  • To Add an Enterprise Server Instance
  • To define an XA resource (XAR) for an enterprise server region
  • To Change the Number of ES licenses
  • To Change the Number of SEPs
  • To Change the System Directory
  • 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 Dynamic Debugging
  • To Enable or Disable an XA Resource
  • To Export Server Information
  • 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

  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 Enable Dynamic Debugging

  1. In the table of servers on the Home page of Enterprise Server Administration, find the row for the server that you want to configure, and click Edit in the left hand column.
  2. In the Server > Properties > General section, select Allow Dynamic Debugging.
  3. Click OK to confirm your changes.
Important: You must restart the server for the changes to take effect.
Parent topic: Work with Servers


To View the Communications Console Log for an Enterprise Server Instance

  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

  • 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

  • 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

  • To Import a Repository
  • To Export the Repository
  • To Restore the Repository
  • To Delete the Repository
Parent topic: Enterprise Server Task Index


Work with WebSphere MQ

  • To start a WebSphere MQ trigger monitor
  • To stop a WebSphere MQ trigger monitor
  • To generate a PSB for a Trigger Monitor
  • To create an XA resource for a trigger monitor
  • To enable MQ listener support
  • To create an MQ listener
  • To edit an MQ listener
  • To view MQ listener or writer details
  • To stop and restart an MQ listener
  • To delete an MQ listener
Parent topic: Enterprise Server Task Index


To start a WebSphere MQ trigger monitor

  1. Copy the supplied file CSQ4TRMN.JCL to an appropriate location. This file can be found in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src folder.
  2. Edit the QMGRNAME and INITQUEUENAME parameters to match the WebSphere MQ Queue Manager and Initiation Queue objects.
  3. Change the job class if required.
  4. Ensure that an initiator for the job class has been started.
  5. Submit CSQ4TRMN.JCL using the JCL Control Page under Enterprise Server Monitor and Control, or by using the cassub command.
Parent topic: Work with WebSphere MQ
Parent topic: WebSphere MQ


To stop a WebSphere MQ trigger monitor

  1. Copy the supplied file CSQ4STOP.JCL to an appropriate location. This file can be found in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src folder.
  2. Edit the PARM line to specify the appropriate Queue Manager and Initiation Queue.
  3. Submit CSQ4STOP.JCL using the JCL Control Page under Enterprise Server Monitor and Control, or by using the cassub command.
Attention: The trigger monitor should be stopped before stopping the Enterprise Server region.
Parent topic: Work with WebSphere MQ
Parent topic: WebSphere MQ


To generate a PSB for a Trigger Monitor

  1. Copy the supplied file CSQ4TRMN.PSB to an appropriate location. This file can be found in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src folder.
  2. At a command prompt enter the following command:
    mfims psbgen csq4trmn.psb nocls echo(enderr,0,55)
Parent topic: Work with WebSphere MQ
Parent topic: WebSphere MQ


To create an XA resource for a trigger monitor

Follow the steps in the topic To define an XA resource (XAR) for an enterprise server region using the following properties:

For one-phase commit transactions
ID | MQXA
Name | MQSERIES
Module | DFHEIBMQ
Open string | TPM=ESCICS,AXLIB=casaxlib,QMNAME=queue manager name
Enabled | checked

Example

TPM=CICS,AXLIB=casaxlib,QMNAME=TESTQ,CHANNEL_TESTQ,TCP,123.10.20.135(1414)
For two-phase commit transactions
ID | MQXA
Name | MQSERIES
Module | ESMQXA
Open string TPM=CICS,AXLIB=casaxlib,QMNAME=queue manager name, CHANNEL, TRPTYPE, CONNAME
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.
QMNAME
The name of the queue manager. This is a mandatory parameter.
CHANNEL
Optional - the name of an MQI channel. If this parameter is supplied, the CONNAME parameter must also be supplied.
TRPTYPE
Optional - the communications protocol for the MQI channel. The default is TCP. The following are valid values:
LU62
SNA LU 6.2
NETBIOS
NetBIOS
SPX
IPX/SPX
TCP
TCP/IP
CONNAME
Optional - the network address of the queue manager (connection name). 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.

Example Open String

TPM=CICS,AXLIB=casaxlib,QMNAME=TESTQ,CHANNEL_TESTQ,TCP,123.10.20.135(1414)
Note: If you specify the CHANNEL, TRPTYPE, and CONNAME parameters, you must also set the MQSERVER environment variable, providing the same parameter values. See WebSphere MQ-Specific Environment Variables for more information.
Enabled | checked
Parent topic: Work with WebSphere MQ
Parent topic: Resources
Parent topic: WebSphere MQ
Related tasks
To define an XA resource (XAR) for an enterprise server region
To Start ESMAC for an enterprise server instance


To enable MQ listener support

Note: Ensure that any duplicate entries for WebSphere MQ support are removed from the SIT, as this could cause connection conflicts.
  1. On the Home page of Enterprise Server Administration, click Edit next to the name of the enterprise server for which you want to enable WebSphere MQ support.
  2. The Edit page that appears contains a hierarchy of tabs. Click the Server, Properties, MQ, and General tabs.
  3. Check MQ listener support enabled; then click Apply.
Note: You can also enable MQ listener support by setting the ES_MQ_LISTENER environment variable, and by using the casout command.
Parent topic: Work with WebSphere MQ
Parent topic: WebSphere MQ


To create an MQ listener

Note: Ensure that any duplicate entries for WebSphere MQ support are removed from the SIT, as this could cause connection conflicts.
To create a listener in Enterprise Server Administration
  1. Ensure that MQ listener support is enabled for your enterprise server instance. See To enable MQ listener support for instructions.
  2. On the Home page of Enterprise Server Administration, click Edit next to the name of the enterprise server for which you want to create an MQ listener.
  3. Click Server, Properties, MQ, and MQ Listeners tabs.
  4. Click Add.
  5. In the Name field, type a name for the new MQ listener.
  6. In the MQ Queue Name field, type the name of an existing MQ queue.
  7. In the MQ Queue Manager Name field, type the name of the MQ Queue Manager that contains the queue specified in the MQ Queue Name field.
  8. Ensure that Enabled is checked (default).
  9. Click Add.
To create a listener in ESMAC
  1. Ensure that MQ listener support is enabled for your enterprise server instance. See To enable MQ listener support for instructions.
  2. Start ESMAC for the enterprise server instance where you have enabled MQ listener support.
  3. On the ESMAC sidebar under Resources, select MQ from the drop-down menu.
  4. Click Listeners.
  5. Click New.
  6. In the Name field, type a name for the new MQ listener.
  7. In the Queue field, type the name of an existing MQ queue.
  8. In the Queue Manager field, type the name of the MQ Queue Manager that contains the queue specified in the Queue field.
  9. Click Start.
Note: You can also create an MQ listener using the casout command.
Parent topic: Work with WebSphere MQ
Parent topic: WebSphere MQ


To edit an MQ listener

  1. On the Home page of Enterprise Server Administration, stop the enterprise server instance where the MQ listener is defined.
  2. Click Edit next to the name of the enterprise server instance.
  3. Click the Server, Properties, MQ, and MQ Listeners tabs.
  4. Click Edit next to the MQ listener you want to edit.
  5. Modify the fields and controls as required.
  6. Click OK.
Parent topic: Work with WebSphere MQ
Parent topic: WebSphere MQ


To view MQ listener or writer details

  1. Start ESMAC for the enterprise server instance that is running the MQ listener or writer you want to view.
  2. On the ESMAC sidebar under Resources, select MQ from the drop-down menu.
  3. Click either Listeners or Writers.
  4. Click the Details button that corresponds to the listener or writer you want to view.
Note: You can also view listener and writer details using the casout command.
Parent topic: Work with WebSphere MQ
Parent topic: WebSphere MQ


To stop and restart an MQ listener

  1. Start ESMAC for the enterprise server instance that is running the MQ listener.
  2. On the ESMAC sidebar under Resources, select MQ from the drop-down menu.
  3. Click Listeners.
  4. Click the Details button that corresponds to the listener you want to stop and/or restart.
  5. Click Stop to stop the listener, or click Start to restart it.
  6. Click Refresh to update the status (optional).
Note:
  • You can also stop and restart listeners using the casout command.
  • You can stop a writer; however stopping a writer deletes the writer.
  • A writer cannot be restarted once it has been stopped (deleted).
Parent topic: Work with WebSphere MQ
Parent topic: WebSphere MQ


To delete an MQ listener

To delete a listener from Enterprise Server Administration
  1. From ESMAC, stop the listener you want to delete. See To stop and restart an MQ listener for instructions.
  2. On the Home page of Enterprise Server Administration, stop the enterprise server instance where the MQ listener is defined.
  3. Click Edit next to the name of the enterprise server for which you want to edit an MQ listener.
  4. Click Server, Properties, MQ, and MQ Listeners tabs.
  5. Click Edit next to the MQ listener you want to delete.
  6. Click Delete.
  7. If you are sure you want to delete the listener, potentially disabling the MQ-IMS Bridge, click OK.
To delete a listener from ESMAC
  1. Start ESMAC for the enterprise server instance that is running the MQ listener you want to delete.
  2. On the ESMAC sidebar under Resources, select MQ from the drop-down menu.
  3. Click Listeners.
  4. Click the Details button that corresponds to the listener you want to delete.
  5. Click Stop to stop the listener.
  6. Click Delete.
Note: You can also delete listeners using the casout command.
Parent topic: Work with WebSphere MQ
Parent topic: WebSphere MQ


CICS Support Tasks

  • Control and Configuration
  • Resources
Parent topic: Enterprise Server Task Index
Parent topic: CICS Support
Parent topic: Mainframe Support for Deployed Applications


Control and Configuration

The following control and configuration tasks are available:

  • To change the SIT associated with a server
  • To configure CICS search paths
  • To enable MSS for an existing enterprise server
  • To send a message to all 3270 terminals
  • To specify a listener for TN3270 terminals
  • To view and delete interval control elements
  • To view resource locks
Parent topic: CICS Support Tasks


To change the SIT associated with a server

  1. Click Home.
  2. Stop the server whose SIT you want to change:
  3. In the table of servers click Edit to the left of the row for the server whose SIT you want to change.
  4. Click Properties > MSS.
  5. Specify the new SIT in System Initialization Table.

    If this entry is not present, the SIT associated with a server defaults to DFH$IVP, the SIT for the CICS application that you use to perform the installation verification procedure.

  6. Click Apply.
  7. Start the server:
  8. Start ESMAC:
  • To stop a server Instance
  • To start an enterprise server instance
  • To Start ESMAC for an enterprise server instance
Parent topic: Control and Configuration
Parent topic: Changing the SIT for an MSS-Enabled Server
Related information
To stop an enterprise server
To start an enterprise server
To start ESMAC for a server
To enable MTO for an enterprise server
To configure CICS search paths
To specify a listener for TN3270 terminals
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To modify a resource
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To send a message to all 3270 terminals


To configure CICS search paths

  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 configure CICS search paths for.
  2. Click the MSS tab.
  3. Enter the search path for CICS application programs in Transaction Path.
  4. Enter the search path for CICS VSAM datasets in VSAM File Path.
  5. Enter the search path for CICS BMS load modules in Map Path.
  6. Enter the search path for CICS resource definition files in Resource Definition File Path.
Note:

In all the path fields except Resource Definition File Path you can specify multiple paths by separating them with a semicolon character (;), for example, to set the search path for VSAM files you could enter

d:\cics\files;d:\cics\files2

in VSAM File Path.

Parent topic: Control and Configuration
Parent topic: Configuring CICS Search Paths
Parent topic: To enable MSS for an existing enterprise server
Related information
To enable MTO for an enterprise server
To configure CICS search paths
To specify a listener for TN3270 terminals
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To modify a resource
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To send a message to all 3270 terminals


To enable MSS for an existing enterprise server

  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 enable MSS.
  2. Click the MSS tab.
  3. Check Mainframe Subsystem Support enabled.

    This is the minimum you need do to enable MSS. By default the enterprise server uses the SIT DFH$IVP. The startup lists, groups and resources used by the enterprise server will, therefore, be those defined by DFH$IVP.

  4. If you want to use a SIT other than DFH$IVP, specify the name of the SIT in System Initialization Table.

    If you want to set a SIT that has a $ (dollar) character in its name you have to escape the $ character, for example MY\$SIT:

  5. If you specified a SIT other than DFH$IVP, specify CICS search paths, unless you are enabling MSS for JCL rather than CICS, in which case search paths are not required.
  6. Click Apply.
  7. Restart your server. The enterprise server will start as a MSS-enabled enterprise server, using either the default SIT, or the SIT you specified.
Note: You can disable or re-enable MSS by unchecking or checking Mainframe Subsystem Support enabled, then clicking OK and stopping and restarting the enterprise server.
  • To configure CICS search paths
Parent topic: Control and Configuration
Parent topic: IMS Support Tasks
Parent topic: Enabling MSS for an Enterprise Server
Parent topic: Enabling JCL for an Enterprise Server
Related concepts
Configuring IMS Printers
Creating and Configuring an Enterprise Server Instance for IMS
Related tasks
To define specific printers for an IMS-enabled enterprise server
To attach to an IMS printer


To send a message to all 3270 terminals

  1. Click Control.
  2. Specify the text of your message in Message all.
  3. Click Send.
Parent topic: Control and Configuration
Parent topic: Sending Messages to All Terminals
Related information
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 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 specify a listener for TN3270 terminals

  1. In the table of servers on the Home page of Enterprise Server Administration, click Details in the Communications Processes cell for the server to which you want to add the listener.
  2. Click Add in the Listeners column for the communications process to which you want to add the listener.
  3. In the Name field, specify a suitable name (for example, tn3270).
  4. Allow Endpoint Protocol to default to TCP.
  5. In Endpoint Address), set the port number for the listener to *.nnnn, where nnnn is a port number. You can use any number above 5000 that isn't in use.
  6. In the Supported Conversation Type group, click TN3270.
  7. Click Add.

    The Communications Processes page is redisplayed showing that the listener was added.

  8. Click Home.
  9. Stop the enterprise server.
  10. Restart the enterprise server.

    This has the effect of starting the listener.

Parent topic: Control and Configuration
Parent topic: Using Telnet 3270 terminal emulators
Parent topic: Specifying a Listener for TN3270 Terminals


To view and delete interval control elements

  1. Click the dropdown menu in the Resources group.
  2. Select Active.
  3. Click ICE. You see the Interval Control Elements (Active) page, containing a list of active ICE definitions.
  4. Click Delete button to the left of the row containing the interval control element you want to delete. The item is deleted immediately, and a message is displayed at the top of the ICE information confirming the deletion.
Note: You can delete interval control elements only if you have the appropriate permissions.
Parent topic: Control and Configuration
Parent topic: Controlling CICS Resources
Related information
To enable MTO for an enterprise server
To configure CICS search paths
To specify a listener for TN3270 terminals
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To modify a resource
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To send a message to all 3270 terminals


To view resource locks

  1. Click the dropdown menu in the Resources group.
  2. Click Active.
  3. Click Lock. You see the Lock page, containing information about the current resource locks. This display is in two parts. The first lists the locks held and applied for. The second part lists the resources. Information in the two parts is related by resource IDs.
Parent topic: Control and Configuration
Parent topic: Viewing Locks
Related information
To enable MTO for an enterprise server
To configure CICS search paths
To specify a listener for TN3270 terminals
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To modify a resource
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To send a message to all 3270 terminals


Resources

The following Resources tasks are available:

  • To create a resource from an existing resource
  • To create a resource group
  • To create a resource table
  • To create a SIT
  • To create a startup list
  • To delete a resource
  • To modify a resource
  • To view a dump of a resource
  • To view active resources
  • To view and delete data queue items
  • To view detailed information for a resource
  • To view resources by group
  • To view resources by startup list
  • To view resources by type
Parent topic: CICS Support Tasks


To create a resource from an existing resource

  1. Click Details on any of the pages that list resources.
  2. Click Copy.

    You can find this button at the bottom of the page.

    ESMAC opens a new page, containing the values carried over from the previous page.

  3. In the Name field, enter a name for the resource.
  4. In pages that have a Group selector, select the group you want the resource to belong to.
  5. Edit fields and/or change controls to the values you require for your new resource.
  6. Click Add.

    The resource is added to the group you specified, or to the list of SITs, groups or startup lists.

Parent topic: Resources
Parent topic: Controlling CICS Resources
Related information
To enable MTO for an enterprise server
To configure CICS search paths
To specify a listener for TN3270 terminals
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To modify a resource
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To send a message to all 3270 terminals


To create a resource group

  1. Click Resources, by Group.
  2. Click Groups.
  3. Click New.
  4. Specify a name and a description for the group.
  5. Click Add.
  6. Click Group List.
  7. Add resources to the group as required: click one of the buttons at the foot of the page (FCT, TST etc), create the new table, and from the table page click Group List to return to the group list. Repeat to add more resources.
Parent topic: Resources
Parent topic: Resources
Related concepts
Defining IMS Resources
IMS-enabled Enterprise Server Administration using ESMAC
Related tasks
To Start ESMAC for an enterprise server instance


To create a resource table

  1. Select Resources, by Type.
  2. Click one of the table buttons (for example, FCT or DCT).
  3. Scroll to the bottom of the page.
  4. Click the button corresponding to the resource table you want to create (for example, FCT or DCT).

    The entry page corresponding to the button you clicked is displayed.

  5. Edit fields and/or change controls to the values you require for your new resource.

    The help for the page explains the meanings and values of controls and fields. To display the context help, click Body in the Help group in the sidebar.

  6. Click Add.

    The resource is added to the group you specified on the page.

Parent topic: Resources
Parent topic: Database Managers Supported
Related information
To enable MTO for an enterprise server
To configure CICS search paths
To specify a listener for TN3270 terminals
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To modify a resource
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To send a message to all 3270 terminals


To create a SIT

  1. Click Resources, by Group.
  2. Click SIT.
  3. Click New.
  4. Specify a name and description.
  5. Choose a startup list for the group from the list in Startup List.
  6. Edit fields or change controls to the values you require for your new SIT.

    The help for the page explains the meanings and values of controls and fields. To display the context help, click This page in the Help group in the sidebar.

  7. Click Add.

    The page is refreshed showing the SIT you have just added.

Parent topic: Resources
Related information
To enable MTO for an enterprise server
To configure CICS search paths
To specify a listener for TN3270 terminals
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To modify a resource
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To send a message to all 3270 terminals


To create a startup list

  1. Click Resources, by Group.
  2. Click Startup.
  3. Click New.
  4. Specify a name and description.
  5. Check Production if the startup list is for a production system.
  6. Specify a group to add to the startup list in 01.
  7. Click Add.

    A new empty row has been added, with the number 02, and icons have been added at the end of row 01 allowing you to move the group at this position up or down, or to delete it. When you move a group up or down, you change the order in which the resources are loaded at startup.

  8. Repeat steps 6 and 7 on the next row and click Apply. Continue until you have specified all the groups in the resource list.
Parent topic: Resources
Related information
To enable MTO for an enterprise server
To configure CICS search paths
To specify a listener for TN3270 terminals
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To modify a resource
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To send a message to all 3270 terminals


To delete a resource

  1. Click Details on any of the pages that list resources.
  2. click Delete on the detailed information page.
Note: If you do not have the required permissions to delete resources, the Delete button is not shown.
Parent topic: Resources
Related information
To enable MTO for an enterprise server
To configure CICS search paths
To specify a listener for TN3270 terminals
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To modify a resource
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To send a message to all 3270 terminals


To modify a resource

  1. Click Details on any of the pages that list resources.

    The detailed information page shows various information relating to the resource you selected. The page title reflects the resource and the method you chose to view it. For example, if you choose to view resources by startup list, click FCT to display a list of FCTs, and then click Details next to an FCT listed in the table, the detailed information page for the FCT you selected is displayed. The detailed information page has the title CICS FCT - fct_name (grp), where fct_name is the name of the FCT, and grp the group to which the FCT belongs. In this case, the detailed information page displays all of the values set for the FCT.

  2. Edit the fields or change controls on the page as required.
  3. Click Apply. If your changes are successfully applied, you see the message "Update successful".
Note: If you do not have the required permissions to modify resources, the Apply button is not shown.
Parent topic: Resources
Parent topic: Resources
Related concepts
Defining IMS Resources
IMS-enabled Enterprise Server Administration using ESMAC
Related tasks
To Start ESMAC for an enterprise server instance


To view a dump of a resource

  1. Click Details on any of the pages that list resources.
  2. click Dump on the detailed information page. The dump is taken, formatted, and displayed.
  3. When you finished viewing the dump, click Back on your browser. This returns you to the details page you were viewing before you initiated the dump.
Parent topic: Resources
Related information
To enable MTO for an enterprise server
To configure CICS search paths
To specify a listener for TN3270 terminals
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To modify a resource
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To send a message to all 3270 terminals


To view active resources

  1. Click the dropdown menu in the Resources group.
  2. Select Active.
    The following buttons are displayed:
    • DCT
    • FCT
    • ICE
    • JCT
    • Lock
    • PCT
    • PPT
    • TST
    • T-Type
    • SysC
    • URIMAP
    • TCPIPSv
    • TRCLASS
  3. Click one of the buttons (except for Lock and ICE) to display a page that contains a table listing all the active resources of that type. The page is called rsc (active), where rsc is the type of resource, such as DCT. For example, if you click FCT, the FCT (active) page is displayed, which lists all the active FCTs.

    Each row of the table lists the name of a resource, and gives further information that depends on the type of resource. For example, the DCT (active) page lists the name of the DCT, its state, and the type of DCT; the PPT page gives the name of the PPT, the type of PPT, and the programming language specified for the PPT.

    Each row also contains a Details button. Click this to display the detailed information page for the resource.

    The TST page also provides a table of actual data queues, including those created for interval control element data records. You can delete data queues on the TST page.

Parent topic: Resources
Parent topic: Controlling CICS Resources
Related information
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To enable MTO for an enterprise server
To configure CICS search paths
To specify a listener for TN3270 terminals
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To modify a resource
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server
To send a message to all 3270 terminals


To view and delete data queue items

  1. Click the dropdown menu in the Resources group.
  2. Select Active.
  3. Click TST. You see the TST (active) page, containing a list of active TST definitions in the upper half, and a table of actual data queue items in the lower half. These include data queues associated with interval control elements.
  4. Click Delete button to the left of the row containing the data queue item you want to delete. The item is deleted immediately, and a message is displayed at the top of the TST information confirming the deletion.
Note: You can delete data queue items only if you have the appropriate permissions.
Parent topic: Resources
Parent topic: Controlling CICS Resources
Related information
To enable MTO for an enterprise server
To configure CICS search paths
To specify a listener for TN3270 terminals
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To modify a resource
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To send a message to all 3270 terminals


To view detailed information for a resource

  1. Click Details on any of the pages that list resources.

    The detailed information page displays various information relating to the resource you selected.

    The page title shows the resource and the method you chose to view it.

    For example, if you choose to view resources by startup list, click FCT to display a list of FCTs. Then click Details next to an FCT listed in the table. The detailed information page for the FCT you selected is displayed.

    The detailed information page has the title CICS FCT - fct_name (grp), where fct_name is the name of the FCT, and grp the group to which the FCT belongs. In this case, the detailed information page displays all of the values set for the FCT.

Parent topic: Resources
Parent topic: Controlling CICS Resources


To view resources by group

  1. Click the dropdown menu in the Resources group.
  2. Select by Group. The following buttons are displayed:
    • Groups - click this to view a list of all groups on this enterprise server. The page CICS Resource Groups is displayed, which lists the resource groups.
    • Startup Lists - click this to view a list of all startup lists on this enterprise server. The page CICS Startup Lists is displayed, which lists all startup lists.
    • SIT - click this to view all a list of all SITs available to this enterprise server. The CICS System Initialization Tables page is displayed, which lists all SITS.

    Each page displayed when you click one of the above buttons contains a table that lists the resources relevant to that button. For example, the CICS System Initialization Tables page, displayed when you click SIT, lists the SITs available.

    Each row of the table provides the name of the resource, and further information on that resource. For example, the CICS System Initialization Tables page shows the name of the SIT, the startup list for the SIT, and a short description of the SIT.

    Each row also contains a Details button. Click this to display the detailed information page for the resource.

Parent topic: Resources
Parent topic: Controlling CICS Resources
Related information
To enable MTO for an enterprise server
To configure CICS search paths
To specify a listener for TN3270 terminals
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To modify a resource
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To send a message to all 3270 terminals


To view resources by startup list

  1. Click the dropdown menu in the Resources group.
  2. Select by Start L. A number of buttons are displayed.
  3. Click one of the buttons to display a page that contains a table listing all the resources of that type for the current startup list. The current startup list is the startup list defined in the SIT that was initiated when the enterprise server was started.

    The page displayed is called CICS Startup List list, where list is the name of the startup list initiated by the SIT.

    Each row of the table lists the name of a resource of the type you selected, and gives further information that depends on the type of resource. For example, if the current SIT used the startup list DFH$IVP, and you clicked DCT, the page displayed is called CICS Startup List DFH$IVP, and lists the DCTs available to the startup list.

    Each row also contains a Details button. Click this to display the detailed information page for the resource.

Parent topic: Resources
Parent topic: Controlling CICS Resources
Related information
To enable MTO for an enterprise server
To configure CICS search paths
To specify a listener for TN3270 terminals
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To modify a resource
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To send a message to all 3270 terminals


To view resources by type

  1. Click the dropdown menu in the Resources group.
  2. Select by Type. A number of buttons are displayed.
  3. Click one of the buttons to display a page that contains a table that lists all the resources of that type known to the current enterprise server.

    The page displayed is called CICS Defined rsc, where rsc is the name the type of resource you clicked.

    Each row of the table gives the name of a resource of the type you selected, and gives further information that depends on the type of resource. For example, if you clicked DCT, the page displayed is called CICS Defined DCT, and lists the DCTs known to the enterprise server.

    Each row also contains a Details button. Click this to display the detailed information page for the resource.

Parent topic: Resources
Parent topic: Controlling CICS Resources
Related information
To enable MTO for an enterprise server
To configure CICS search paths
To specify a listener for TN3270 terminals
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To modify a resource
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To send a message to all 3270 terminals


IMS Support Tasks

  • To create an IMS-enabled enterprise server from the Enterprise Developer IDE
  • To create an MSS-enabled enterprise server for IMS applications from Enterprise Server
  • To enable MSS for an existing enterprise server
  • To enable IMS for an MSS-enabled enterprise server
  • To specify the location of generated files
  • To specify the location of application files
  • To define a message processing region
  • To enable IMS Connect
  • To define how MFS attributes are coded
  • To define the MFS null character
  • To run an IMS transaction from a 3270 session
  • To start a temporary MPR
  • To perform a cold start
  • Message Queue
  • Printers
  • Resources
  • Transactions
  • WebSphere MQ
Parent topic: Enterprise Server Task Index
Parent topic: Mainframe Support for Deployed Applications


To create an IMS-enabled enterprise server from the Enterprise Developer IDE

  1. From the Enterprise Developer IDE, open Server Explorer.

    If it is hidden, display it by choosing Server Explorer.

  2. Typea name for your enterprise server instance into the Name field.
  3. Check either 32-bit or 64-bit.
  4. Click the browse button next to the Template field.

    This opens the location of the Enterprise Developer server templates which is by default.

  5. Select IMSTemplate.xml, and click Open.
  6. In the Associate with projects box, check an IMS project that contains the application you want to run on the new enterprise server.
Parent topic: IMS Support Tasks
Related concepts
Creating and Configuring an Enterprise Server Instance for IMS


To create an MSS-enabled enterprise server for IMS applications from Enterprise Server

  1. Start Enterprise Server Administration using one of the following methods:
    • From the Start menu: Click Start > All Programs > Micro Focus Enterprise Developer > Configuration > Enterprise Server Administration. This starts Enterprise Server Administration in a browser outside of the IDE.
    • From your Web browser, enter http://localhost:86 into the Address field.
  2. Click Add.
  3. In the Server Name field, type a name for the new enterprise server instance.
  4. Choose a Working mode option; then click Next.
  5. In the Server Type group, click Micro Focus Enterprise Server with Mainframe Subsystem Support; then click Next.
  6. In the Creation Options group, ensure that Set TN3270 listener is checked; then enter a port number into the Using port field. This is the port number used when you connect to the enterprise server with your TN3270 emulator.
  7. In the Description field, type a description of the new enterprise server
  8. Click Add.

    This displays the Enterprise Server Administration Home page with your new server on the list of available enterprise servers.

  9. Configure the new enterprise server instance for IMS.
Parent topic: IMS Support Tasks
Related concepts
Creating and Configuring an Enterprise Server Instance for IMS


To enable IMS for an MSS-enabled enterprise server

  1. On the Home page of Enterprise Server Administration, click Edit next to the name of the enterprise server you want to enable.
  2. The Edit page that appears contains a hierarchy of tabs. Click the Server, Properties, MSS, IMS and General tabs.
  3. Ensure that Mainframe Subsystem Support enabled is checked, then check IMS enabled.
  4. Click Apply.
Parent topic: IMS Support Tasks
Related concepts
Configuring IMS Printers
Creating and Configuring an Enterprise Server Instance for IMS
Related tasks
To define specific printers for an IMS-enabled enterprise server
To attach to an IMS printer
To add PCT entries to a resource group
Related information
To specify the location of generated files
To add PCT entries to a resource group
To add a message processing region to a resource group
To define a transaction manually


To specify the location of generated files

  1. From the Enterprise Server Administration Home page, in the table of servers, click Edit to the left of the row for the server you want to change.
  2. The Edit page that appears contains a hierarchy of tabs. Click the Server, Properties, MSS, IMS and General tabs.
  3. In both the GEN file directory and Configuration directory fields, specify the name of the folder that contains your generated DBD and PSB files. You can enter multiple locations, each separated by a semi-colon.
  4. Click Apply to save the change.
  5. Click the Server, Properties, MSS, IMS, TM and General tabs.
  6. In the MFS path field, specify the name of the folder that contains your generated MFS files. You can enter multiple locations, each separated by a semi-colon.
  7. Click Apply to save the changes.
  8. Click Home to return to the Home page of Enterprise Server Administration.
Parent topic: IMS Support Tasks
Related concepts
Creating and Configuring an Enterprise Server Instance for IMS
Related tasks
To add PCT entries to a resource group


To specify the location of application files

  1. From the Enterprise Server Administration Home page, in the table of servers, click Edit to the left of the row for the server you want to change.
  2. The Edit page that appears contains a hierarchy of tabs. Click the Server, Properties, MSS, IMS, TM and General tabs.
  3. In the Application Path field, type the full path to your COBOL source files and copybooks.
  4. In the Transaction definition file directory field, type the full path to your transaction definition file. By default, this is dfhdrdat located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\cas .
  5. Click Apply to save the changes.
  6. Click the Server, Properties, MSS, IMS, and DB tabs.
  7. In the Database path field, type the full path to your PSB and DBD database files.
  8. Click Apply to save the changes.
Parent topic: IMS Support Tasks
Related concepts
Creating and Configuring an Enterprise Server Instance for IMS


To define a message processing region

  1. From the Enterprise Server Administration Home page, click Server, Properties, MSS, IMS, TM, and MPRs.
  2. Click Add.
  3. In the Name field, type a name for the MPR.
  4. In the Transaction Class field, type a three-digit number such as 001.
  5. Click Add.
  6. Click Home to return to the Home page of Enterprise Server Administration.
Note: You can specify a maximum of four classes in the Transaction Class field. You must separate each class by a comma. The classes you specify must be less than 32-bytes long. If you specify more than four classes only the first four are used. When you start the enterprise server instance you see a message (CASIP0013I) in the console.log that shows which classes have been registered for use.
Parent topic: IMS Support Tasks


To enable IMS Connect

  1. From the Enterprise Server Administration Home page, click the Listeners tab.
  2. Click Add.
  3. Enter a unique name for the new listener.
  4. From the Endpoint Protocol drop-down list, select TCP .
  5. Enter an appropriate port for IMS Connect in the Endpoint Address text box.
  6. Select a Supported Conversation Type of Custom and enter mfcs-ims-connect in the text box.
  7. Optionally, add trace details in the Configuration Information text box, for example:
    [Trace]
trace=y
data-trace=all
allmax=255
  8. Click Add.
Parent topic: IMS Support Tasks
Related concepts
IMS Connect


To define how MFS attributes are coded

Transaction level

  1. In the dropdown list under Resources on the ESMAC menu, select IMS.
  2. Click Transact.
  3. Click Details for the transaction to be modified, or New if you are creating a new transaction.
  4. Select the appropriate value for the MFS Attributes field. Where you set this to 'Default', the value set at Enterprise Server level (see below) will be used.
  5. Click Add or Apply as appropriate.

Enterprise Server level

  1. On the Home page of Enterprise Server Administration, click Edit next to the name of the enterprise server you want to enable.
  2. The Edit page that appears contains a hierarchy of tabs. Click the Server, Properties, MSS, IMS and TM tabs.
  3. Select the desired value for MFS attribute bias field.
    Note: You can override this value at transaction level.
  4. Click Apply.
Note: This task is only applicable if the codeset bias being used is 'ASCII'.
Parent topic: IMS Support Tasks
Related tasks
To define the MFS null character


To define the MFS null character

Transaction level

  1. In the drop-down list under Resources on the ESMAC menu, select IMS.
  2. Click Transact.
  3. Click Details for the transaction to be modified, or New if you are creating a new transaction.
  4. Select the appropriate value for the MFS Null field. Where you set this to [default], the value set at Enterprise Server level (see below) will be used.
  5. Click Add or Apply as appropriate.

Enterprise Server level

  1. On the Home page of Enterprise Server Administration, click Edit next to the name of the enterprise server you want to enable.
  2. The Edit page that appears contains a hierarchy of tabs. Click the Server, Properties, MSS, IMS and TM tabs.
  3. Select the desired value for MFS null character field.
    Note: You can override this value at transaction level.
  4. Click Apply.
Note: This task is only applicable if the codeset bias being used is 'ASCII'.
Parent topic: IMS Support Tasks
Related tasks
To define how MFS attributes are coded


To run an IMS transaction from a 3270 session

Note: See Configuring IMS-enabled Enterprise Servers for more info on how to define transactions in an enterprise server.

Before you run your IMS transaction in an enterprise server you must first run the /IMS transaction to set up the enterprise server to run in IMS mode. Once you have done this, you run an IMS transaction in the same way as you would run it on the mainframe. If you run it from a 3270 terminal or emulator, you enter transaction IDs at the terminal. Note that on a PC the keys assigned to act as the CICS keys depend on your TN3270 emulator. For example, in many cases the Escape key is used as the 3270 Clear key, and the right-hand Ctrl key is used as the 3270 Enter key.

To run an IMS transaction from a 3270 session:

  1. Enter /IMS to switch the enterprise server to IMS mode.
  2. Enter the name of your transaction. If the name of the transaction is shorter than eight characters, add a trailing space to the end of it.
Note:
  • To switch from IMS mode back to CICS mode, use the /CIC transaction.
  • The /CIC and /IMS transactions is defined in the DFHSIGN group. To add these transactions to your resource definition file you must run the caspcupg command, as described in the section Adding IMS-specific Resource Definitions in the chapter Configuring IMS-enabled Enterprise Servers for IMS in your Mainframe Subsystem Support Configuration and Administration Guide.
Parent topic: IMS Support Tasks


To start a temporary MPR

As well as defining permanent message processing regions, you can define temporary ones that exist only until an enterprise server is stopped.

To start a temporary MPR:

  1. In the dropdown list under Resources on the ESMAC menu, select IMS.
  2. Click Control in the Resources part of the ESMAC menu.

    The IMS Control page that appears is for starting MPRs and creating an internal diagnostic view of IMS TM message queues.

  3. In MPR Classes field, type the list of message classes you want this MPR to be able to run.
  4. If you are defining an MPR for transactions that you want to debug, check Debug.
  5. Click Start.

    The MPR starts immediately and lasts until the enterprise server is stopped.

Note: You can specify a maximum of four classes in the Transaction Class field. You must separate each class by a comma. The classes you specify must be less than 32-bytes long. If you specify more than four classes only the first four are used. When you start the enterprise server instance you see a message (CASIP0013I) in the console.log that shows which classes have been registered for use.

Like all SEPs, any MPRs you define are shown, together with their statuses, on the SEPs page in ESMAC. Click SEPs near the top left of the ESMAC menu to display this. MPRs are displayed in the IMS MPR section.

Parent topic: IMS Support Tasks


To perform a cold start

If your message processing regions for an enterprise server become unresponsive for some reason you need to perform a cold start. Performing a cold start involves deleting the IMS message queue for an enterprise server, so any outstanding messages are lost and need to be resubmitted after the cold start.

To perform a cold start you delete the file %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\ES_name\imsmesgq.dat, where ES_name is the name of the enterprise server whose message processing regions are unresponsive.

Parent topic: IMS Support Tasks


Message Queue

  • To dynamically adjust the IMS message queue configuration
  • To enable dynamic IMS message queue performance tuning
  • To dynamically tune IMS message queue performance
Parent topic: IMS Support Tasks


To dynamically adjust the IMS message queue configuration

  1. Start your enterprise server region.
  2. From the Enterprise Server Administration Home page, click the Details button in the Status column for your enterprise server region.
  3. Click ES Monitor & Control.
  4. On the sidebar menu under Resources, select IMS from the drop-down menu; then click the Control button below.
  5. In the TM System Overview and Control section, modify the Message Queue Max and/or Cushion fields as required. See the IMS Control topic for a description of each.
  6. When you have completed your changes, click Apply.

    Changes take effect immediately.

Parent topic: Message Queue
Related concepts
Dynamic IMS Message Queue Expansion
Dynamic IMS Message Queue Performance Tuning
Related reference
IMS-Specific Environment Variables
Server Instance Properties: MSS IMS TM General
IMS Control


To enable dynamic IMS message queue performance tuning

  1. If started, stop your enterprise server region .
  2. From the Home page in Enterprise Server Administration, click the Edit button that corresponds to your enterprise server region.
  3. Open the Server > Properties > General tabs.
  4. In the Configuration Information field, add an [ES-Environment] section, and set the ES_TMC_AGGREGATE environment variable. For example, to disable flush operations:
    [ES-Environment]
ES_TMC_AGGREGATE=,D
    See Dynamic IMS Message Queue Performance Tuning for detailed descriptions of each ES_TMC_AGGREGATE environment variable option.
  5. Click Apply.
Parent topic: Message Queue
Related concepts
Dynamic IMS Message Queue Performance Tuning
Dynamic IMS Message Queue Expansion
Related tasks
To dynamically tune IMS message queue performance
Related reference
IMS-Specific Environment Variables
Server Instance Properties: MSS IMS TM General
IMS Control


To dynamically tune IMS message queue performance

  1. In Enterprise Server Administration, be sure that you have set the ES_TMC_AGGREGATE environment variable. See To enable dynamic IMS message queue performance tuning for details.
  2. Start your enterprise server region.
  3. From the Enterprise Server Administration Home page, click the Details button in the Status column for your enterprise server region.
  4. Click ES Monitor & Control.
  5. On the sidebar menu under Resources, select IMS from the drop-down menu; then click the Control button below.
  6. In the TM System Overview and Control section, modify any of the following as required:
    • Transaction Threshold
    • Q Flush Aggregate, on, ms, Flush disable
    • Keypoint Freq

    See the IMS Control topic for a description of each.

  7. When you have completed your changes, click Apply.

    Changes take effect immediately.

Parent topic: Message Queue
Related concepts
Dynamic IMS Message Queue Performance Tuning
Related tasks
To enable dynamic IMS message queue performance tuning
Related reference
IMS-Specific Environment Variables
Server Instance Properties: MSS IMS TM General
IMS Control


Printers

  • To define specific printers for an IMS-enabled enterprise server
  • To enable printer security for an IMS-enabled enterprise server
  • To attach to an IMS printer
Parent topic: IMS Support Tasks
Related concepts
Creating and Configuring an Enterprise Server Instance for IMS


To define specific printers for an IMS-enabled enterprise server

Note: This topic applies to Use Case 3: Define Specific Printers to Enterprise Server from the topic Configuring IMS Printers. See Configuring IMS Printers for information on LU1 and LU3 Term Model definitions.
  1. Start ES Monitor & Control for your IMS-enabled enterprise server.
  2. Edit the IMSGRP resource definition, found in the IMSSTRT startup list.
    Note: The IMSGRP resource definition is found in the IMSSIT system initialization table. If you have not specified IMSSIT for this enterprise server, create a new resource group.
  3. On the CICS GROUP page, click Term.
  4. In the Name field, type a four-character name for the new Term; generally, this is the last four characters of the Net Name, and must be unique within the Term name namespace for an enterprise server. A name conflict encountered for either specifically or dynamically defined clients can prevent definitions from installing properly at run time.
  5. Type a meaningful description into the Description field.
  6. From the Model drop-down list, select No.
  7. In the Net Name field, type a name. See Assigning Client Names for more information.
  8. In the Terminal Type field, type the terminal type that represents the printer. For example, for an LU3 printer, type LU3PRINT. LU3PRNT is a supplied T-TYPE definition in the DFHTERM definition group.
  9. Ensure that the Fixed Transaction field is set to /IMS. This specification ensures that Enterprise Server publishes this device to theEnterprise Server IMS TM.
  10. Click Add.
Parent topic: Printers
Related concepts
Configuring IMS Printers
Creating and Configuring an Enterprise Server Instance for IMS
Related tasks
To enable MSS for an existing enterprise server
To enable IMS for an MSS-enabled enterprise server
To start an enterprise server instance
To Start ESMAC for an enterprise server instance


To enable printer security for an IMS-enabled enterprise server

Note: This topic applies specifically to the use of legacy SNT security for Enterprise Server. If using external security managers, the security manager that controls authentication (i.e., manages user IDs) must contain a user definition that matches the Net Name specified for the printer.
  1. Start ES Monitor & Control for your IMS-enabled enterprise server.
  2. From the list on the left side of the page, click Users.
  3. Click the Details button that corresponds to CICSUSER.
  4. Check Local ES Security Enabled.
  5. Click Apply.
  6. Add a user definition for each printer, providing a user ID for each that is the same as the printer's Net Name.
Parent topic: Printers
Related concepts
Creating and Configuring an Enterprise Server Instance for IMS
Related tasks
To start an enterprise server instance
To Start ESMAC for an enterprise server instance


To attach to an IMS printer

In your TN3270 emulator, specify the client name (NETNAME), which is the IMS LTERM name under which it operates. For example, in Rumba type this name into the Device Name field on the TN3270 tab of the Connection Configuration dialog box. See Assigning Client Names for more information.

Parent topic: Printers
Related concepts
Configuring IMS Printers
Creating and Configuring an Enterprise Server Instance for IMS
Related tasks
To enable MSS for an existing enterprise server
To enable IMS for an MSS-enabled enterprise server
To start an enterprise server instance
To Start ESMAC for an enterprise server instance


Resources

Note: You must perform the following tasks from the Enterprise Server Monitor and Control (ESMAC) interface.
  • To Start ESMAC for an enterprise server instance
  • To create a resource group
  • To modify a resource
  • To add a message processing region to a resource group
  • To add a resource group to a startup list
  • To add PCT entries to a resource group
  • To create an XA resource for a trigger monitor
Parent topic: IMS Support Tasks
Related tasks
To Start ESMAC for an enterprise server instance


To add a message processing region to a resource group

  1. In the dropdown list under Resources on the ESMAC menu, select By Group.
  2. Click Groups, then click Details next to the resource group you want to update.
  3. Click JES.
  4. Specify IMS MPR in the Type field, the relevant classes in the Classes field, and an appropriate text in the Name and Description fields.
  5. Click Add.
  6. Click Group List.
Note: You can specify a maximum of four classes in the Transaction Class field. You must separate each class by a comma. The classes you specify must be less than 32-bytes long. If you specify more than four classes only the first four are used. When you start the enterprise server instance you see a message (CASIP0013I) in the console.log that shows which classes have been registered for use.
Note:

Defining a message processing reigon for an enterprise server in this way causes a message processing region to start each time the enterprise server is started. For information on creating a message processing region that only exists until an enterprise server stops, see the section Temporary MPRs in the chapter Administering IMS-enabled Enterprise Servers in your Mainframe Subsystem Support Configuration and Administration Guide.

Parent topic: Resources
Related tasks
To Start ESMAC for an enterprise server instance
To add PCT entries to a resource group
Related information
To enable IMS for an MTO-enabled enterprise server
To specify the location of genned files
To add PCT entries to a resource group
To define a transaction manually


To add a resource group to a startup list

  1. In the list of buttons under Resources on the ESMAC menu, click Startup.
  2. Click Details next to the entry for the startup list to which you want to add the resource group.
  3. Specify the name of the resource group in the empty field at the bottom of the list of resource groups.
  4. Click Apply.
  5. Click Home to return to the Home page of Enterprise Server Administration.
Parent topic: Resources
Related concepts
Defining IMS Resources
Related tasks
To Start ESMAC for an enterprise server instance
Related information
To enable IMS for an MTO-enabled enterprise server
To specify the location of genned files
To add PCT entries to a resource group
To add a message processing region to a resource group
To define a transaction manually


To add PCT entries to a resource group

  1. In the drop-down list under Resources on the ESMAC menu, select By Group.
  2. Click Groups, then click Details next to the resource group you want to update.
  3. Click PCT.
  4. Specify the name of the transaction in the Name field and the name of the associated program in the Program Name field.
  5. Click Add.
  6. Click Group List.
Parent topic: Resources
Related tasks
To Start ESMAC for an enterprise server instance
To define a transaction manually
To enable IMS for an MSS-enabled enterprise server
To specify the location of generated files
To add a message processing region to a resource group


Transactions

  • To define a transaction manually
  • To export IMS transactions
  • To import IMS transactions
Parent topic: IMS Support Tasks


To define a transaction manually

  1. From the ESMAC menu, in the drop-down list under Resources, select IMS.
  2. Click Transactions; then click New.
  3. On the Create, View and Edit an IMS Transaction page, specify the values you require for your new transaction.
  4. Click Add; then Apply.
Note: Add the new transaction to a resource group as a PCT entry.
Parent topic: Transactions
Related concepts
Defining IMS Resources
Defining IMS Transactions
Related tasks
To add PCT entries to a resource group
Related reference
Create, View and Edit an IMS Transaction


To export IMS transactions

Option 1: Export from a stage 1 file
The stage 1 file is read and all the transaction definitions are extracted into a transaction file.
To create a transaction file from a stage 1 file:
  1. Download your stage 1 file from the mainframe.
  2. Open an Enterprise Developer command prompt.
  3. Change to the directory that contains your downloaded stage 1 file.
  4. Enter the following:
    mfims stage1ext stage1file transactionfile
    where:
    stage1file | The stage 1 file downloaded from the mainframe.
    transactionfile | The name of the transaction file to be created.

    The transaction file is created in the current directory.

Option 2: Export from imsgen2.dat
To create a transaction file from an imsgen2.dat file:
  1. Open an Enterprise Developer command prompt.
  2. Enter the following:
    mfims tranexp [transactionfile]
    where:
    transactionfile The name of the transaction file to be created. Optional. If not specified, the name of the transaction file defaults to tranexp.txt.

    The transaction file is created in the current directory.

    Note: If the imsgen2.dat file is not in the current directory, it must be in the directory specified by the ES_IMSLIB environment variable.
Parent topic: Transactions
Related concepts
Defining IMS Transactions


To import IMS transactions

  1. Open an Enterprise Developer command prompt.
  2. Change to the directory that contains your transaction file.
    Note: If you want to import into an existing imsgen2.dat file, be sure that either the transaction file and the imsgen2.dat file are in the current directory, or that you have set the ES_IMSLIB environment variable to point to the location of the imsgen2.dat file.
  3. Enter the following:
    mfims stage1imp transactionfile [ADDREPL] [DELEXIST]

    where:

    transactionfile | The transaction file created from a stage 1 file or from Enterprise Server.
    ADDREPL | If the imsgen2.dat already exists, specifies adding new transactions and replacing existing transactions. If you do not specify ADDREPL, new transactions are added but existing transactions are left unchanged.
    DELEXIST | If the imsgen2.dat already exists, specifies that all the existing transaction definitions in the imsgen2.dat file be deleted before importing extracted transactions.
Parent topic: Transactions
Related concepts
Defining IMS Transactions


WebSphere MQ

  • To create an MQ listener
  • To create an XA resource for a trigger monitor
  • To delete an MQ listener
  • To delete an MQ writer
  • To edit an MQ listener
  • To enable MQ listener support
  • To generate a PSB for a Trigger Monitor
  • To start a WebSphere MQ trigger monitor
  • To stop and restart an MQ listener
  • To stop a WebSphere MQ trigger monitor
  • To view MQ listener or writer details
Parent topic: IMS Support Tasks


To delete an MQ writer

  1. Start ESMAC for the enterprise server instance that is running the writer you want to delete.
  2. On the ESMAC sidebar under Resources, select MQ from the drop-down menu.
  3. Click Writers.
  4. Click the Details button that corresponds to the writer you want to delete.
  5. Click Stop to stop the writer.

    Stopping the writer deletes it automatically.

Note: You can also delete writers using the casout command.
Parent topic: WebSphere MQ


JCL Support Tasks

The following JCL support tasks are available:

  • JCL Configuration
  • Deploying and Running JCL Applications
  • Spool Queue Tasks
  • JCL Catalog Tasks
  • Micro Focus FTP Utility MFFTP
    The MFFTP Utility allows FTP batch processing from JCL on a mainframe.
Parent topic: Enterprise Server Task Index
Parent topic: JCL Support
Parent topic: Mainframe Support for Deployed Applications


JCL Configuration

The following JCL configuration tasks are available:

  • To add a service for JCL
  • To define a batch initiator or printer SEP
  • To enable JCL support
  • To specify a handler for JCL requests
  • To automatically defer printing for specified message classes
Parent topic: JCL Support Tasks


To add a service for JCL

  1. Click Details in the Objects column for the server you want to add the service to.
  2. Click Add.
  3. In both Name and Service Class type: MF JES
  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 Available Handlers, select MFRHJCL. Then click Select Handler. The selection is active immediately.
  7. In Description type a suitable description, such as Job Entry Subsystem service.
  8. 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.
Parent topic: JCL Configuration


To define a batch initiator or printer SEP

This defines a batch initiator or printer SEP that will be a permanent feature of the enterprise server, starting up whenever the enterprise server is started. If you want to start a batch initiator or printer SEP "on the fly" while the enterprise server is running, to run waiting jobs immediately, see To start a batch initiator or printer immediately.
  1. If you are starting a printer, make sure the enterprise server is running and was started from the command line.
  2. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button.
  3. Click Edit by the server you want to add the initiator or printer to.
  4. Make sure the Server and Properties tabs are selected, then click MSS and then JES.
  5. Click Initiator or Printer.
  6. Click Add.
  7. Enter details in the fields.

    In Class, type the list of job classes you want this initiator to run, or this printer to print; for example, ABC. The JOB CLASS of a JCL jobstream must match the class of a batch initiator SEP in order for the SEP to run the job. The MSGCLASS or SYSOUT class must match the class of a batch printer SEP in order for the SEP to print the output.

  8. For a printer, select a printer in the list in Printer Name.
  9. Click Add.
Parent topic: JCL Configuration
Parent topic: SEPs for JCL
Related concepts
Configuring Enterprise Server for WebSphere MQ Trigger Monitors
Related information
To start a batch initiator or printer immediately
To run a JCL job
To run a JCL job from the command line
To define a batch initiator or printer SEP
To start a batch initiator SEP from the command line
To deploy a JCL application to an enterprise server
To start a batch printer SEP from the command line
To run a JCL job on a remote enterprise server
To view resource locks
To reply to an ACCEPT FROM CONSOLE statement


To enable JCL support

  1. On the Enterprise Server Administration home page, click Edit next to the name of the enterprise server you want to enable.
  2. The Edit page that appears contains a hierarchy of tabs. Make sure the Server and Properties tabs are selected, and click MSS.
  3. Make sure that Mainframe Subsystem Support is checked.
  4. Click JES.
  5. Check Job Entry Subsystem enabled.
  6. Enter values into the fields on the JES tab. Click This Page in the help menu for more information.
  7. Click OK.
  8. Click Apply to save your changes.
Note: You also need to make sure the enterprise server has batch initiators for the JCL job classes you wish to run. See the Related Topics below.
Parent topic: JCL Configuration
Parent topic: Enabling JCL for an Enterprise Server
Related information
To specify a handler for JCL requests
To enable JCL support
To define a batch initiator or printer SEP
To add a service for JCL
To automatically defer printing for specified message classes
To add a service for integration with the Micro Focus Development Tools


To specify a handler for JCL requests

  1. On the Home page of Enterprise Server Administration, look at the Objects column for the enterprise server that you want to start a handler for. One entry there shows the number of handlers available in that enterprise server – it is at least 2, since the Web Services and J2EE handlers are there by default. Click Details next to this Handlers entry.
  2. On the page that appears, click Add.
  3. On the Add Handler page that appears, type MFRHJCL in Module Name, leave Module Path and Configuration Information blank, and type "Handles JCL requests" in Description.
  4. Click Add at the bottom of the page. The list on the Handlers page now includes MFRHJCL.
  5. Click Home on the menu at the left. The Objects column for the server now shows one more handler than before.
  6. Stop the enterprise server.
  7. Restart the enterprise server.

    This has the effect of starting the listener.

Note: You need to specify a handler for JCL requests only if you want to use an existing enterprise server for handling JCL jobs that does not already have this handler defined. Any new MSS-enabled servers you create will automatically have this request handler defined.
Parent topic: JCL Configuration
Related information
To stop an enterprise server
To start an enterprise server
To specify a handler for JCL requests
To enable JCL support
To define a batch initiator or printer SEP
To add a service for JCL
To automatically defer printing for specified message classes
To add a service for integration with the Micro Focus Development Tools


To automatically defer printing for specified message classes

You can configure your enterprise server to automatically route specified message classes to the Out Hold queue.

  1. On the Home page of ES Admin, click Edit next to the name of the enterprise server you want to enable.
  2. The Edit page that appears contains a hierarchy of tabs. Make sure that the Server>Properties>General tab is selected.
  3. In the Configuration Information field, set the ES_SYSOUT_HOLD environment variable to the message classes that you want to route to the Out Hold queue. For example:
    [ES-Environment]
ES_SYSOUT_HOLD=AB
    In this case, message classes A and B will be routed to the Out Hold queue.
    Note: The maximum size of this value is 36 characters.
  4. Click OK and restart your enterprise server.
Parent topic: JCL Configuration
Related information
To specify a handler for JCL requests
To enable JCL support
To define a batch initiator or printer SEP
To add a service for JCL
To automatically defer printing for specified message classes
To add a service for integration with the Micro Focus Development Tools


Deploying and Running JCL Applications

The following tasks are available for deploying and running JCL applications:

  • To deploy a JCL application to an enterprise server
  • To view resource locks
  • To reply to an ACCEPT FROM CONSOLE statement
  • To run a JCL job
  • To run a JCL job from the command line
  • To run a JCL job on a remote enterprise server
  • To start a batch initiator or printer immediately
  • To start a batch initiator SEP from the command line
  • To start a batch printer SEP from the command line
  • To stop a JES initiator from the command line
Parent topic: JCL Support Tasks


To deploy a JCL application to an enterprise server

  • Copy the executable files of the application to the folder where the enterprise server has been configured to look for executables when JCL was enabled.
Parent topic: Deploying and Running JCL Applications
Related information
To enable JCL support
To run a JCL job
To run a JCL job from the command line
To define a batch initiator or printer SEP
To start a batch initiator or printer immediately
To start a batch initiator SEP from the command line
To deploy a JCL application to an enterprise server
To start a batch printer SEP from the command line
To run a JCL job on a remote enterprise server
To view resource locks
To reply to an ACCEPT FROM CONSOLE statement


To view resource locks

  1. Click the dropdown menu in the Resources group.
  2. Click JES.
  3. Click Lock. You see the Lock page, containing information about the current resource locks. This display is in two parts. The first lists the locks held and applied for. The second part lists the resources. Information in the two parts is related by resource IDs.
Parent topic: Deploying and Running JCL Applications
Parent topic: Running and Controlling JCL Jobs
Related information
To run a JCL job
To run a JCL job from the command line
To define a batch initiator or printer SEP
To start a batch initiator or printer immediately
To start a batch initiator SEP from the command line
To deploy a JCL application to an enterprise server
To start a batch printer SEP from the command line
To run a JCL job on a remote enterprise server
To view resource locks
To reply to an ACCEPT FROM CONSOLE statement


To reply to an ACCEPT FROM CONSOLE statement

  1. Submit the job in the normal way, using Submit on ESMAC's JES Control page.
  2. The job begins and the first few lines of the job log appear on the Control page, ending with
    Processed jcl-filename

    where jcl-filename is the full pathname of the JCL file you submitted. The job pauses at this point.

  3. Now click Job at the bottom left-hand corner of the Control page to go to the Job page.
  4. Enter the text of your reply in Enter, below the line
    CASBJ0035I Console input request is pending.
  5. Click Reply.
  6. The job now continues.
Note: If you return to the Control page before you have entered your reply, you will see that a Pending Replies group has been added at the top of the page. There is a line of information for each pending reply, with a Reply button next to each line. If you click Reply on this page, you are returned to the Job page. The job remains paused until you enter a reply.
Parent topic: Deploying and Running JCL Applications
Parent topic: Interacting with JCL Jobs
Related information
To run a JCL job
To run a JCL job from the command line
To define a batch initiator or printer SEP
To start a batch initiator or printer immediately
To start a batch initiator SEP from the command line
To deploy a JCL application to an enterprise server
To start a batch printer SEP from the command line
To run a JCL job on a remote enterprise server
To view resource locks
To reply to an ACCEPT FROM CONSOLE statement


To run a JCL job

Important: If you are using Microsoft Internet Explorer's Enhanced Security Configuration feature you must disable it before following this procedure. For example:
  1. Close all instances of Internet Explorer.
  2. Select Start > Administrative Tools > Server Manager. If a User Account Control dialog box appears, click Continue..
  3. Under Security Summary, choose Configure IE ESC.
  4. Make sure both Administrators and Users are not selected.
  5. Click OK.
  1. In the dropdown list under Resources on the ESMAC menu, select JES.
  2. Click Control in the Resources part of the ESMAC menu.

    The JCL Control page that appears is for submitting jobs, and for starting additional printers and batch initiators.

  3. In the field by the Submit button, type the path and name of the JCL file you want to run. This file must exist on the machine on which the enterprise server is running.
  4. Click Submit.
Parent topic: Deploying and Running JCL Applications
Parent topic: Running and Controlling JCL Jobs


To run a JCL job from the command line

  1. Make sure the enterprise server you want to use is running, and was started from the command line.
  2. At an Enterprise Developer command prompt, enter:
    start cassub -jpath\jcl-file

    where path and jcl-file specify the JCL file to run. -j is the keyword identifying this parameter. There must be no space after the -j. For example:

    cassub -jc:\jclbatch\jclbatch.jcl

    You can specify the –j parameter more than once, in order to submit several JCL files in the same command.

    If you are submitting the job to an enterprise server that is local to your machine, you can use the –r parameter to specify the enterprise server to run the job. If you omit it, ESDEMO is assumed.

    If you want to submit the job to a remote enterprise server, you need to specify the -saddress parameter, where address is the address of the listener associated with the server's MF JES service.

    The job is run by the most recently started available initiator that can handle the class specified on the JOB card.

Parent topic: Deploying and Running JCL Applications
Related reference
cassub
Related information
To run a JCL job
To run a JCL job from the command line
To define a batch initiator or printer SEP
To start a batch initiator or printer immediately
To start a batch initiator SEP from the command line
To deploy a JCL application to an enterprise server
To start a batch printer SEP from the command line
To run a JCL job on a remote enterprise server
To view resource locks
To reply to an ACCEPT FROM CONSOLE statement


To run a JCL job on a remote enterprise server

Important: If you are using Microsoft Internet Explorer's Enhanced Security Configuration feature you must disable it before following this procedure. For example:
  1. Close all instances of Internet Explorer.
  2. Select Start > Administrative Tools > Server Manager. If a User Account Control dialog box appears, click Continue.
  3. Under Security Summary, choose Configure IE ESC.
  4. Make sure both Administrators and Users are not selected.
  5. Click OK.
  1. Open ES Admin for the remote enterprise server.
  2. In the list of servers, click Details in the Current Status column for the server to which you want to submit the job. The server must already be started.
  3. Click ES Monitor and Control.
  4. Submit the job using JES > Control in the usual way.
Note:
  • The JCL must be local to the machine you are submitting the job to.
  • While you are connected to the remote machine, you can view spool queues and the catalog in the usual way.
Parent topic: Deploying and Running JCL Applications
Parent topic: Running and Controlling JCL Jobs


To start a batch initiator or printer immediately

This starts a batch initiator or printer SEP "on the fly". You create it while the enterprise server is running, and it will immediately run any waiting jobs of the right class. It lasts until the enterprise server is stopped. If you want to define a batch initiator or printer SEP that will be a permanent feature of the enterprise server, starting up whenever the enterprise server is started, see To define a batch initiator or printer SEP.

  1. If you are starting a printer, make sure the enterprise server was started from the command line.
  2. In the dropdown list under Resources on the ESMAC menu, select JES.
  3. Click Control in the Resources part of the ESMAC menu.

    The JCL Control page that appears is for submitting jobs, and for starting additional printers and batch initiators.

  4. Select Initiator or Printer from the dropdown list by the Type field.
  5. In Classes, type the list of job classes you want this initiator to run, or this printer to print; for example, ABC. The JOB CLASS of a JCL jobstream must match the class of a batch initiator SEP in order for the SEP to run the job. The MSGCLASS or SYSOUT class must match the class of a batch printer SEP in order for the SEP to print the output.
  6. If you are defining an initiator for jobs that you want to debug, click Debug.
  7. For a printer, select a printer in the list in Printer Name.
  8. Click Start.

    The batch initiator or printer will start immediately and last until the enterprise server is stopped.

Parent topic: Deploying and Running JCL Applications
Parent topic: On-the-fly SEPs for JCL
Related information
To define a batch initiator or printer SEP
To run a JCL job
To run a JCL job from the command line
To start a batch initiator or printer immediately
To start a batch initiator SEP from the command line
To deploy a JCL application to an enterprise server
To start a batch printer SEP from the command line
To run a JCL job on a remote enterprise server
To view resource locks
To reply to an ACCEPT FROM CONSOLE statement


To start a batch initiator SEP from the command line

  1. Make sure the enterprise server you want to use is running, and was started from the command line.
  2. At an Enterprise Developer command prompt, enter:
    casout /iclasslist

    where classlist specifies the job classes that the initiator is to be able to run. There must be no space after the /b. For example:

    casout -iABC

    You can use the /r parameter to specify the enterprise server to run the job. If you omit it, ESDEMO is assumed.

Parent topic: Deploying and Running JCL Applications


To start a batch printer SEP from the command line

  1. Make sure the enterprise server was started from the command line.
  2. At a command prompt, enter:
    start casout -bclasslist -n"printer" -renterprise-server

    or:

    start casout -bclasslist -n"printer" -renterprise-server -xprinter-exit

    where classlist specifies the job classes that the SEP is to handle, printer is the name of the printer (as defined in Windows), enterprise-server is the enterprise server to start it in (default ESDEMO), and the optional printer-exit specifies a Printer Exit module. For example:

    start casout -bABC -n"HP LaserJet 4L" -rESDEMO

    or:

    start casout -bABC -n"HP LaserJet 4L" -rESDEMO -xSAMPPRNX

    Note that it’s advisable to run this command in a separate session, using the Windows start command as shown.

Parent topic: Deploying and Running JCL Applications


To stop a JES initiator from the command line

Use the casout command with the /t operand to stop a JES initiator without stopping the region.

Example

if test "$#" -ne 2
then
  echo "*** ERROR - missing parameters"
  echo "usage: stopclass region-name class"
  exit 99
fi

region=`echo $1 | sed 's/ .*$//'`
class=`echo $2 | tr '[a-z]' '[A-Z]'`

COBDIR=/opt/microfocus/cobol
export COBDIR
PATH=$COBDIR/bin:$PATH
export PATH
LD_LIBRARY_PATH=$COBDIR/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
casout -r$region -v
if test "$?" -eq 0
then

  casout -r$region -v | grep 'tor '$class | cut -d" " -f5 >startClass.txt
  processID=`cat startClass.txt | sed 's/ .*$//'`
  casout -r$region -t$processID
else
  echo "*** ERROR - Return Code: "$?
  exit $?
fi

jobrc=$?

case "$jobrc"
in
  0)   echo "Processing Successful: "$jobrc;;
  15)  echo "*** ERROR - Invalid Region Name: "$region
       echo "*** Return Code: "$jobrc;;
  99)  echo "*** ERROR - JES not available for Region: "$region
       echo "*** Return Code: "$jobrc;;
  199) echo "*** ERROR - User ID not authorised: "$region
       echo "*** Return Code: "$jobrc;;
  255) echo "*** ERROR - Region is not started: "$region
       echo "*** Return Code: "$jobrc;;
  *)   echo "*** ERROR - Return Code: "$jobrc;;
esac
Parent topic: Deploying and Running JCL Applications


Spool Queue Tasks

The following spool queue tasks are available:

  • To delete a job
  • To delete a job output file
  • To delete all jobs in a queue
  • To hold or release a job
  • To update control information for a job
  • To view details of a job output file
  • To view details of a job's execution
  • To view the step condition codes for a job
  • To view the contents of a job output file
  • To view the spool queues
Parent topic: JCL Support Tasks


To delete a job

  1. On the Spool page, click the button for the queue that contains the job.
  2. Click the check box to the left of the row describing the job you want to delete.
  3. Click Delete.
Note: An alternative method is to go to the JOBnnnnn page, where nnnnn is the number of the job, and click Delete
Parent topic: Spool Queue Tasks
Parent topic: Managing and Viewing Spool Queues
Related information
To delete a job output file
To delete all jobs in a queue
To hold or release a job
To update control information for a job
To view details of a job output file
To view details of a job's execution
To view the contents of a job output file
To view the spool queues


To delete a job output file

  • On the job output file details page click Purge.
Parent topic: Spool Queue Tasks
Parent topic: Managing and Viewing Spool Queues
Related information
To delete a job
To delete all jobs in a queue
To hold or release a job
To update control information for a job
To view details of a job output file
To view details of a job's execution
To view the contents of a job output file
To view the spool queues
To view the spool queues
To view details of a job's execution
To hold or release a job
To update control information for a job
To delete a job
To view details of a job output file
To delete a job output file
To view the step condition codes for a job
To view the contents of a job output file
To delete all jobs in a queue


To delete all jobs in a queue

  1. On the Spool page, click the button for the queue that contains the jobs.
  2. Click the check box to the left of the Display button. This selects all the jobs in the queue.
  3. Click Delete.
Parent topic: Spool Queue Tasks
Parent topic: Managing and Viewing Spool Queues
Related information
To delete a job
To delete a job output file
To hold or release a job
To update control information for a job
To view details of a job output file
To view details of a job's execution
To view the contents of a job output file
To view the spool queues


To hold or release a job

  • On the JOBnnnnn page, where nnnnn is the number of the job, or on the job output file details page, click Hold or Release.
Note:
  • Hold changes to Release after you have clicked it, and Release changes back to Hold after a further click. The Status field also changes accordingly.
  • If the job is in the input queue when you click Hold, it is not executed until you release it. If the job is in the output queue when you click Hold, the output files are not printed until you release it.
  • If you have also changed the value for Class or Priority, the change is applied.
Parent topic: Spool Queue Tasks
Parent topic: Managing and Viewing Spool Queues
Related information
To delete a job
To delete a job output file
To delete all jobs in a queue
To update control information for a job
To view details of a job output file
To view details of a job's execution
To view the contents of a job output file
To view the spool queues


To update control information for a job

  1. On the JOBnnnnn page, where nnnnn is the number of the job, or on the job output file details page, specify a new Class or Priority or both.
  2. Click Update.
Parent topic: Spool Queue Tasks
Parent topic: Managing and Viewing Spool Queues
Related information
To delete a job
To delete a job output file
To delete all jobs in a queue
To hold or release a job
To view details of a job output file
To view details of a job's execution
To view the contents of a job output file
To view the spool queues


To view details of a job output file

  • On the JOBnnnnn page, where nnnnn is the number of the job, click Details against the name of the output file that you want to view details for.
Parent topic: Spool Queue Tasks
Parent topic: Managing and Viewing Spool Queues
Related information
To delete a job
To delete a job output file
To delete all jobs in a queue
To hold or release a job
To update control information for a job
To view details of a job's execution
To view the contents of a job output file
To view the spool queues


To view details of a job's execution

  1. On the Spool page, click the button for the queue that contains the job.
  2. Click the check box to the left of the row describing the job that you want to view.
  3. Click Display.
Note: You can also view details of a job's execution by entering the job number in the field next to the Job button, then clicking Job. This facility is available on some of the other JCL-related pages in ESMAC.
Parent topic: Spool Queue Tasks
Parent topic: Running and Controlling JCL Jobs
Parent topic: Managing and Viewing Spool Queues
Related information
To delete a job
To delete a job output file
To delete all jobs in a queue
To hold or release a job
To update control information for a job
To view details of a job output file
To view the contents of a job output file
To view the spool queues


To view the step condition codes for a job

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Details button next to the DD Name JESYSMSG.

    The page for the JESYSMSG data set is displayed.

  2. In Format: choose StepCC.
  3. Click Display.

    The condition codes for all steps in the job are displayed. Click Back on your browser toolbar to return to the JESYSMSG page.

Parent topic: Spool Queue Tasks
Parent topic: Managing and Viewing Spool Queues


To view the contents of a job output file

  1. On the job output file details page, find the line with a Display button on the left side.
  2. Update the fields Start and for to indicate which records you want to view. Clear the for field to view all the records in a file. The default is that you view the first 10000 records or the whole file, whichever is the shorter.
  3. In Format: choose the codeset that you want to be used for the display:
    • ASCII The contents are known to be in ASCII format.
    • EBCDIC The contents are known to be in EBCDIC format.
    • Both The contents are unknown, and the display will be rendered correctly for the most part irrespective of the codeset used to create the file.
    • Dump The contents are rendered in "dump" format; that is, hexadecimal on the left and character on the right.
    • StepCC The condition codes for all steps in the job are shown. This format applies only to the JESYSMSG data set.
  4. If you want to see extra details check Details.
  5. Click Display.

    The contents of the output file are displayed. Click Back on your browser toolbar to return to the job output file page.

Note: If you are viewing the spool queues from the Enterprise Server Administration page, and you attempt to view all the records in a large job output file, be aware that your browser will take some time to display all the records, and might run out of memory.
Parent topic: Spool Queue Tasks
Parent topic: Managing and Viewing Spool Queues
Related information
To delete a job
To delete a job output file
To delete all jobs in a queue
To hold or release a job
To update control information for a job
To view details of a job output file
To view details of a job's execution
To view the spool queues


To view the spool queues

  1. In the dropdown list under Resources on the ESMAC menu, select JES.
  2. Click Spool in the Resources part of the ESMAC menu.
  3. The page that appears shows one of the spool queues. Click one of the row of buttons to select which queue is displayed.

    You can change the order in which entries are listed by clicking on the column headings.

  4. If the list of jobs in the queue spans more than one page, to view other pages, specify a page number and click go or click either > (next page) or < (previous page).
    Tip:
    • If the page number you specify does not exist, clicking go opens the last page.
    • If you are viewing the last page, clicking > opens the first page.
    • If you are viewing the first page, clicking < redisplays the first page.
    • Specifying a page number greater than the total number of pages and then clicking < redisplays the current page.
    • Specifying a page number greater than the total number of pages and then clicking > opens the last page.
Parent topic: Spool Queue Tasks
Parent topic: Managing and Viewing Spool Queues
Related information
To delete a job
To delete a job output file
To delete all jobs in a queue
To hold or release a job
To update control information for a job
To view details of a job output file
To view details of a job's execution
To view the contents of a job output file
To view the spool queues
To view details of a job's execution
To hold or release a job
To update control information for a job
To delete a job
To view details of a job output file
To delete a job output file
To view the step condition codes for a job
To view the contents of a job output file
To delete all jobs in a queue


JCL Catalog Tasks

The following JCL catalog tasks are available:

  • To copy a catalog entry for a data set
  • To create a catalog entry for a data set
  • To delete a catalog entry for a data set
  • To update a catalog entry for a data set
  • Importing and Exporting a Catalog: import export utility
    Describes how to use the catalog import-export utility
  • To view the catalog
  • To view the contents of a data set
  • To view the details of a catalog entry
  • Searching for Catalog Entries
Parent topic: JCL Support Tasks


To copy a catalog entry for a data set

  1. On the Data Catalog page, click DCB against the entry that you want to copy.
  2. On the Catalog Entry page click Copy.
  3. Specify the properties of the data set in the new catalog entry.
  4. Click Apply.
Parent topic: JCL Catalog Tasks
Parent topic: Viewing the Catalog and Data Sets


To create a catalog entry for a data set

  1. On the Data Catalog page, click New.
  2. Specify the properties of the data set.
  3. Click Apply.
Parent topic: JCL Catalog Tasks
Parent topic: Viewing the Catalog and Data Sets


To delete a catalog entry for a data set

  1. On the Data Catalog, page click DCB against the entry that you want to delete.
    Note: No entries are shown on the Data Catalog page until you click the List button. You can use the field adjacent to the List button to enter a filter string to limit the number of entries displayed. For example, enter "ABC*" to view only those data sets that begin with ABC. You can use a single asterisk as a wild card.
  2. Click Delete.
Parent topic: JCL Catalog Tasks
Parent topic: Viewing the Catalog and Data Sets


To update a catalog entry for a data set

  1. On the Data Catalog page, click DCB against the entry that you want to update.
    Note: No entries are shown on the Data Catalog page until you click the List button. You can use the field adjacent to the List button to enter a filter string to limit the number of entries displayed. For example, enter "ABC*" to view only those data sets that begin with ABC. You can use a single asterisk as a wild card.
  2. Change the properties of the data set as required.
  3. Click Apply.
Parent topic: JCL Catalog Tasks
Parent topic: Viewing the Catalog and Data Sets


Importing and Exporting a Catalog: import export utility

The catalog import-export utility is supplied to make it easier to work with the contents of a catalog. You can use the catalog import export utility to:

  • Extract the contents of the system catalog to an XML file
  • Import a system catalog from a source XML file
  • Extract and/or update individual catalog records
Note:

This utility is intended as a tool for use during migrations. It is definitely NOT recommended that you use it for editing the catalog data for live systems. The recommended way of manipulating catalog entries is via JCL, where consistency can be guaranteed. For bulk changes to the PC-DSN field, MVSPCRN is recommended.

Use caution when performing catalog updates. Setting inconsistent field values will cause errors.

Setting the MFSYSCAT environment variable

In order to use the catalog import export utility, you need to set the MFSYSCAT environment variable to the catalog path and filename. For example:
set MFSYSCAT=c:\test\project\catalog.dat

Invoking the catalog import export utility from the command line

The utility can be invoked from the command line or by calling it from another program. Use the syntax:
Call MVSP0033 using ws-command-line
In the command above, ws-command-line is a command with the syntax and parameters described below.

Syntax

MFCATXML FUNC(xxxx) INFILE(filename)
OUTFILE(filename) KEY(xxxx)

The function's operation, and the parameters that you use, varies depending on the value of the FUNC parameter.

Export entire catalog: Func = EXP

Exports the entire catalog to an XML file.

OUTFILE The name of the file to hold the exported data.

Import a catalog: Func = IMP

Imports a catalog from an XML file.

INFILE The name of the file with the catalog data to be imported.

Export specific catalog records: Func = GU

Reads details for specified catalog records and writes them to a file.

INFILE(filename) | The catalog entries for all the MVS DATASET names found in the XML document filename are retrieved
KEY(datasetname) | The record for the single MVS dataset name in the datasetname parameter is retrieved
KEY(@filename) | The records for all the MVS dataset name in the filename parameter are retrieved. filename must be a text file with each successive dataset on a new line.
OUTFILE(filename) | The output file for the catalog records.
Note:
  • One of INFILE(filename), KEY(datasetname) or KEY(@filename) is required. They are mutually exclusive alternatives to specifying the dataset name(s) to be retrieved.
  • OUTFILE(filename) is mandatory.

Insert records into a catalog: Func = ISRT

Reads catalog record details from INFILE and inserts these catalog records.

INFILE(filename) The name of the XML file with the catalog data to be inserted.

Replace existing catalog records: Func = REPL

Reads catalog record details from INFILE and replaces corresponding existing catalog records.

INFILE(filename) The name of the XML file with the catalog data to be replaced.

Delete catalog records: Func = DLET

Deletes catalog records.

INFILE(filename) | Deletes catalog entries for all the MVS DATASET names found in filename.
KEY (datasetname) | Deletes the record for the single dataset name set defined in datasetname.
KEY(@filename) | Deletes all of the catalog records for all the MVS dataset names listed in filename. This file must be a text file with each successive dataset on a new line.
Note: One of INFILE(filename), KEY (datasetname) or KEY(@filename) is required. They are mutually exclusive alternatives to specifying the dataset name(s) to be deleted.

Examples

The following command creates the OUT.XML XML file that contains all of the data held in the catalog identified in the MFSYSCAT environment variable.

MFCATXML FUNC(EXP) OUTFILE(OUT.XML)

The resulting XML file can be edited and then imported using the following command:

MFCATXML FUNC(IMP) INFILE(OUT.XML)
Parent topic: JCL Catalog Tasks
Parent topic: Viewing the Catalog and Data Sets
Parent topic: Administering JCL-enabled Enterprise Servers


To view the catalog

  1. In the dropdown list under Resources on the ESMAC menu, select JES.
  2. Click Catalog in the Resources part of the ESMAC menu.
  3. To limit the entries displayed, enter a filter string in the text field next to the List button. For example, enter "ABC*" to view only those data sets that begin with ABC. You can use a single asterisk as a wild card.
  4. Click the List button.
Note:

In addition to filtering list items, you can control the number of items in the catalog view by setting the ES_ESMAC_DISP_MAX_OVERRIDE environment variable.

For example, the maximum number of items displayed can be set to 100:

configuration:
[ES-Environment]
ES_ESMAC_DISP_MAX_OVERRIDE=100
Parent topic: JCL Catalog Tasks
Parent topic: Viewing the Catalog and Data Sets


To view the contents of a data set

  1. On the Data Catalog, page click DCB against the entry that you want to update.
    Note: No entries are shown on the Data Catalog page until you click the List button. You can use the field adjacent to the List button to enter a filter string to limit the number of entries displayed. For example, enter "ABC*" to view only those data sets that begin with ABC. You can use a single asterisk as a wild card.
  2. Update the fields Start and for to indicate which records you want to view. Clear the for field to view all the records in a file. The default is that you view the first 10000 records or the whole file, whichever is the shorter.
  3. In Codeset choose the codeset that you want to be used for the display.
  4. If you want to see extra details check Details.
  5. Click Display.

    The contents of the data set are displayed. Click Back on your Browser toolbar to return to the Catalog Entry page.

Note: If you are viewing the catalog from the Enterprise Server Administration page, and you attempt to view all the records in a large file, be aware that your browser will take some time to display all the records, and might run out of memory.
Parent topic: JCL Catalog Tasks
Parent topic: Viewing the Catalog and Data Sets


To view the details of a catalog entry

  • On the Data Catalog page, click DCB against the entry that you want to view.
    Note: No entries are shown on the Data Catalog page until you click the List button. You can use the field adjacent to the List button to enter a filter string to limit the number of entries displayed. For example, enter "ABC*" to view only those data sets that begin with ABC. You can use a single asterisk as a wild card.
Parent topic: JCL Catalog Tasks
Parent topic: Viewing the Catalog and Data Sets


Micro Focus FTP Utility MFFTP

The MFFTP utility provides FTP support for JCL-enabled enterprise servers within Micro Focus Enterprise Server. The MFFTP utility provides a support mechanism for batch processes that takes advantage of FTP from JCL on the mainframe.

The MFFTP utility is not a rewrite of an FTP client. It makes use of the platform's existing FTP client or of any third party FTP client installed on the machine.

  • Prerequisites
  • Major Features of the MFFTP Utility
  • Basic Operation
    Describes the three phases of the MFFTP utility. Reading standard FTP control cards, invoking the client and reading the output from the client.
  • Configuring the MFFTP Utility
    Details the environment variables, DD statements, input and output files, manipulation of end-of-line markers, error codes and messages.
  • Running the MFFTP Utility
  • Writing a Module to Support a Third Party FTP Client
    How to configure MFFTP to invoke a third party client.
Parent topic: JCL Support Tasks
Related concepts
Features Added in Enterprise Server 2.3


Prerequisites

The MFFTP utility is installed as part of Micro Focus Enterprise Server.

MFFTP requires:

  • An FTP client on the host system - for example, WS_FTP Pro.
  • A JCL-enabled enterprise server configured to receive JCL jobs.

Known Issues

If the FTP client connects to the FTP server using invalid credentials, and the server neither accepts anonymous access nor performs a timeout after a period of inactivity, the FTP client waits indefinitely and never returns to MFFTP. To resolve this, ensure that the correct credentials are supplied.

Parent topic: Micro Focus FTP Utility MFFTP


Major Features of the MFFTP Utility

The following features of the MFFTP utility relate to MVS datasets:

Fixed Block (FB) file support

Provides support for uploading and downloading FB files to and from the mainframe or non-mainframe servers.

The default values for MFFTP are RECFM=VB and LRECL=256, which are also the default values when uploading to the mainframe.

To upload a file to the mainframe as an FB file, use the following command to change the defaults:

QUOTE SITE RECFM=FB LRECL=XX

To download an MVS dataset as an FB file in the enterprise server, use the LOCSITE command.

Variable Block (VB) file support

Provides support for downloading files from the mainframe or from non-mainframe servers in VB format when the environment variable MFFTP_SENDEOL is set to a value other than ‘NONE’ or when the LOCSITE SBSENDEOL command is used.

If MFFTP_SENDEOL is not set (its default value is ‘NONE’) while downloading, the files are cataloged as VB but there is no file header in the physical file. Because of this, this file is not in a suitable format for uploading back to the mainframe. In such cases, the job ends with MAXCC=U00001 and you receive a message “File status of 39 (attributes mismatch)” in the console.

If MFFTP_SENDEOL is set to ‘CRLF’ while downloading VB files from the mainframe, it correctly creates a VB file with Micro Focus format-style file header and with the contents from the file on the mainframe. Similarly, in the case of non-mainframe servers, if MFFTP_SENDEOL is set to ‘CRLF’, ’CR’ or ’LF’, MFFTP correctly creates the VB file for a ‘GET’ command of a text file with ‘CRLF’, ’CR’, ’LF’ for end-of-line markers, respectively.

A VB file with an appropriate header record can be uploaded to the mainframe, either when MFFTP_SENDEOL is set to a value other than ‘NONE’ or if the LOCSITE command is used with SBSENDEOL=XX. If MFFTP_SENDEOL is not set while uploading a VB file, the ftp fails with error message “451-File transfer failed. File contains records that are longer than the LRECL of the new file.” To indicate the end-of-each record, you need to use the LOCSITE command with SBSENDEOL=CRLF or set MFFTP_SENDEOL=CRLF. If the file to be uploaded is in ASCII format, you must use the ftp command ‘ASCII’.

If SENDEOL is specified, MFFTP creates a temporary file as part of the FTP process. It is called ftpxxxxx.snnn.eol.zzzz, where xxxxx is the JES job number, nnn is the step number and zzzz is a sequence number. This temporary file is created by reading the file to be uploaded and copying its contents. The file is used in the transfer instead of the original physical file. For the PUT command, an end-of-line file (Line Sequential) is always created and used for the transfer of VB files, even if the SENDEOL parameter is not set.

Generation Data Group (GDG) file support

Provides support for uploading and downloading GDG files to and from the mainframe or non-mainframe servers. The GDG files can have different DCB parameters depending on the values specified by the LOCSITE and QUOTE SITE commands. If LOCSITE and QUOTE SITE are not specified, the generated files have default DCB values of RECFM=VB and LRECL=256. This is the same behavior as on the mainframe.

Parent topic: Micro Focus FTP Utility MFFTP
Related reference
MFFTP Statements
MFFTP Environment Variables


Basic Operation

FTP clients in distributed environments do not understand mainframe dataset names. The primary goal of MFFTP is to provide a shell such that mainframe names are translated to distributed file system names and to interact with the Enterprise Server catalog.

In addition, other functions are available to reformat data, such as converting text files, in Micro Focus line sequential format, to mainframe format, fixed or variable length records, as well as converting between character sets.

To achieve this, MFFTP goes through three phases:

  1. Reading standard FTP control cards to create an input file for the client.

    The cards are examined and certain ones are changed before being written to the client input file. Most notable of these are the GET and PUT statements. The local filename in these cases is a mainframe name which will be converted to a distributed file system name as would be seen in the Enterprise Server catalog. If any errors occur, the program terminates.

  2. Invoking the client.

    MFFTP creates a command line and then invokes the command. The client receives the created input cards and executes them to produce an output.

  3. Reading the output from the client.

    MFFTP checks the output to ensure the commands executed correctly. If a command fails, MFFTP terminates with a non-zero return code or aborts. In addition, if files were fetched and need to be reformatted, MFFTP performs this at this point.

  • Differences Between FTP clients on a Mainframe and Distributed Platforms
  • MFFTP Statements
    List of commands with descriptions of action.
Parent topic: Micro Focus FTP Utility MFFTP


Differences Between FTP clients on a Mainframe and Distributed Platforms

There are many differences between the FTP client on the mainframe and those on the distributed platforms, most of these being related to the environment. For example, the distributed platform does not have access to DCB information or space allocations. The MFFTP utility uses the catalog facilities to provide both the missing links between the application requirements of attributes such as DCB and a means to translate between mainframe dataset names and the actual filenames on the distributed platform. When a request is made to FTP to GET or PUT a mainframe dataset, this has to be translated to a native filename.

You can specify default values on the mainframe in one of two ways: hard-code the values in the FTP application or use the SYSFTPD DD statement to specify them. MFFTP supports both methods.

You can make changes at execution time with a LOCSITE statement. Use a LOCSTAT command to display the relevant values and where they came from, for example - SYSFTPD, LOCSITE, an environment variable or a default value.

MFFTP scans the FTP control cards and either checks them, acts upon them, or simply passes them through. The utility expects control cards to start in column 1.

Parent topic: Basic Operation


MFFTP Statements

The following statements are checked and processed:

Command | Description
# or ; or * | Indicates a comment line.
APPEND | See PUT.
ASCII | Specifies that the transfer is in ASCII mode.
BINARY | Specifies that the transfer is in BINARY mode.
BYE | Ends the FTP session. If MFFTP does not find a BYE statement, it inserts one.
CD | Changes directory on remote machine. MFFTP performs a check that "spacey" directory names have been double quoted. If not then it will surround it in double quotes. If single quotes have been used they are replaced with double quotes.
GET

When this is executed, the local name, which would be a mainframe style name, is converted to native format.

If the file does not exist, it is cataloged with the current values as shown by LOCSTat.

If the file already exists within the catalog, the REPlace option must be used, and the existing catalog attributes will be used and the existing file overwritten.

LCD | Changes the directory on the local machine. MFFTP performs a check for "spacey" directory names in the same way that CD does.
LOCSIte

Many of the options of LOCSIte are not relevant to the Enterprise Server environment and are ignored.

The following options are supported:

  • BLKsize or BLOCKSize
  • LRecl
  • PRImary (space allocation)
  • RECfm
  • SECondary (space allocation)
  • SPACETYPE
  • SBSENDEOL
  • MBSENDEOL
  • SBDATACONN
  • MBDATACONN
LOCSTat | Provides a list of the current settings.
MFFTP_VARS | Lists the current settings of all MFFTP variables.
MGET

In order to obtain the list of files to be transferred and cataloged, the utility will attempt to connect to the server to produce a list of matches.

This list will be used to create a series of simple GET statements.

Note: All files are processed and cataloged with the same attributes.
MPUT | The catalog will be scanned to obtain a list of the files that match the filter criteria. A simple PUT will be created for each file that matches the criteria.
OPEN

If used, this must be the first statement.

If the OPEN statement has an IP address or host name, this will be overridden by any on the EXEC statement.

PROMPT | By default, MGET or MPUT prompts for confirmation. If no PROMPT is seen before an MGET or MPUT is encountered, one will be inserted before and after the generated simple statements.
PUT | When this is executed, MFFTP converts the local name, which would be a mainframe style name, to native format.
QUIT | Equivalent to BYE.
TYPE

The distributed platform expects ASCII or BINARY, while the mainframe allows A (ASCII) and I (BINARY).

MFFTP changes the command as appropriate for the respective platform. Using other values causes an error.

USER | MFFTP requires that you specify a user. If the keyword “USER” is not seen, it is assumed to be either the first (if no OPEN statement found) or second (if OPEN statement found) statement.
Parent topic: Basic Operation
Related concepts
Major Features of the MFFTP Utility


Configuring the MFFTP Utility

  • Specifying Environment Variables
    You can set environment variables from within Enterprise Server Administration or, optionally, by specifying the ENVVAR DD statement in JCL.
  • MFFTP Environment Variables
  • MFFTP DD Statements
    List of the DD statements required with MFFTP and there definition.
  • Input and Output Temporary Files
  • Configuring the End-of-Line Marker
    Change the end-of-line marker in the transferred files.
  • Configuring Error Codes
    How FTP client return codes relate to MFFTP error codes.
  • Configuring the Text of Messages
    Specifies how the text for the messages can be altered using sample programs as an example.
Parent topic: Micro Focus FTP Utility MFFTP


Specifying Environment Variables

You set environment variables for MFFTP in the JCL-enabled enterprise server from within Enterprise Server Administration as follows:

  1. Open Enterprise Server Administration.
  2. Click Edit on the row for your server.
  3. On the General page, enter the following in the Configuration Information field:
    [ES-Environment]
MFFTP_var-name=var-value
  4. Click OK.

You can use an optional ENVVAR DD statement to specify environment variable values. You add this in the JCL STEP that runs MFFTP. This can be a physical dataset or instream data, as in the example given in Running MFFTP. The advantage of using this approach is that the values pertain only to the current execution and override any values set within Enterprise Server Administration.

For example - set MFFTP_KEEP to ‘N’ in the Enterprise Server Administration. When the files are required to diagnose an issue you can keep the files by adding the following DD entry in the JCL step:
//ENVVAR   DD *
MFFTP_KEEP=Y
Parent topic: Configuring the MFFTP Utility
Related reference
Running the MFFTP Utility


MFFTP Environment Variables

You can use the following environment variables to configure the MFFTP utility:

MFFTP_ABCODE=nnnn
If MFFTP has to abend, it defaults to a code of U0001. Use this variable to set a value in the range 1-4095.
MFFTP_ABEND=RC8
If MFFTP finds an error in the input stream or encounters an I/O error, the default action is to terminate with a user abend code U0001. Using this environment variable instead stops the program immediately with a return code of 8.
MFFTP_CATALOG_CHARSET=xxx
By default, new datasets are cataloged with the servers character set. You can use this variable to override the character set. Acceptable values are:
  • A
  • ASC
  • ASCII
  • E
  • EBC
  • EBCDIC

If the specified character set does not match the server’s character set, you receive a warning message.

MFFTP_CHECK_221={Y | N}

When MFFTP processes a BYE or a QUIT command, the host FTP client should receive a message prefixed with 221. If no such message is received, this indicates a network or a similar failure.

If this variable is set to Y and the 221 message is not received, the return code is set to 4.

MFFTP_EXIT_EQUALS={N |Y}

By default, if MFFTP detects an error, it exits with a non-zero return code or abends with a U0001. See MFFTP_ABCODE for information about how to change the abend code.

If EXIT=nnnn is coded on the EXEC card PARM, setting this to Y causes MFFTP to return with a return code of nnnn.

MFFTP_CLIENT={FTP | USER}

Sets the FTP client to be invoked.

If this is not specified or is set to FTP, the host's default FTP client is used.

If USER is specified, you also need to specify MFFTP_USR_FTP_PGM, and point to a module that invokes an FTP client.

MFFTP_EPSV={N | Y}

Some FTP servers need to be sent the EPSV command after the USER command. The default is to keep the session as active.

Setting this to Y causes the server to enter into a passive FTP session. Use this if the server uses the IPv6 communications protocol. This enables FTP connections where the user is behind routers or firewalls, where connections over an active PORT/EPRT ftp session might not work.

MFFTP_FTP_DEBUG={1 | 2}

Inserts an FTP DEBUG command into the FTP command stream.

  • A value of 1 inserts the command as the first statement.
  • A value of 2 inserts the command after the logon credentials.

MFFTP_KEEP={N | Y | C}

If set to Y, all work files are kept at the end of the step unless MFFTP_KEEP_IP=N (see below) is also set, in which case the input work file is always deleted.

If set to C, the file is deleted if the return code from the FTP client is 0; otherwise the work files are kept.

MFFTP_KEEP_IP={N | Y}
If set to N, the input work files are deleted at the end of the step, even if MFFTP_KEEP is set to Y.
MFFTP_OUTPUT_LRECL=xxx
By default, the record size (LRECL) of the OUTPUT DD statement is 133-bytes. You can use this variable to change the record size to a maximum value of 512-bytes.
MFFTP_PREFIX={N | Y}
When set to Y, causes the server instance name to be used as a prefix to the temporary filenames.
MFFTP_RETCODE=n1,n2,n3,n4
Determines the return code (condition code) returned to JES. By default, the return codes indicate:
0
No problems encountered.
4
MFFTP received output from the host FTP client that suggested an error, for example an error message in the 5nn or 4nn series. One or more commands might have failed. The “pass” or “fail” defaults can be seen in the supplied code for the MFFTPURR module which you can modify, if necessary.
8
MFFTP did not receive any output from the host FTP client that started with a recognized message number. This usually occurs if the FTP client fails to connect to the FTP server.
16
Some other fatal error.
The above four codes represent n1, n2, n3 and n4 respectively. These may be modified so that, for example, a return code of 8 is always required (MFFTP_RETCODE=0,8,8,8).
Note: All four values must be coded.
MFFTP_SENDEOL={NONE | CR | LF | CRLF}
Specifies the end-of-line characters that are typically found on text files on distributed systems. As an enterprise server instance with Mainframe Subsystem Support (MSS) is emulating a mainframe, using GET scans for the specified characters and removes them, and using a PUT command appends the specified characters to each logical record.
MFFTP_SYSPRINT_LRECL=xxx
By default, the record size (LRECL) of the SYSPRINT DD statement is 133 bytes. You can use this variable to change the record size to a maximum value of 512 bytes.
MFFTP_TEMP_DIR=dir
Specifies an absolute directory path rather than the default data directory where MFFTP creates the temporary files. The directory must already exist and be accessible by the server instance.
Note: On UNIX, ensure that this is entered using the same case as the target directory.
MFFTP_TIME={N | C | L | B}
MFFTP makes a record of the time it starts and ends, and calculates the elapsed time. It also makes a record of the time the FTP client is running. To display these times, set this directive with the following values:
N
Default, indicates no display.
C
Console
L
Listing
B
Both console and listing
MFFTP_TRANSLATE_SAFETY={ON | OFF}
By default, when code page translation is requested (by using the TRAN option on the EXEC card), MFFTP checks that a “round trip” will not corrupt data. It does this by simulating a PUT of a 256 byte area containing x’00’ through x’ff’. It then takes the resulting output and simulates a GET with that data. If the tables are correct, the result from the GET should equal the original data. Use this variable to ignore any warnings if the data does not match.
Note: Use this variable with caution.
MFFTP_UFLAG={N | Y}
Some FTP clients need to have the -u flag set. It stops MFFTP from attempting auto-authentication during the initial connection.
MFFTP_USR_FTP_PGM=program-name
This is required if MFFTP_CLIENT is set to USER. Specifies the name of a user-supplied module that invokes the FTP client.
Note: On UNIX, ensure that this is entered using the same case as the module or MFFTP reports that it is unable to call the module.
MFFTP_VERBOSE_OUTPUT={ON | OFF}
Determines what is written to the print file. By default, MFFTP prints a lot of information, including the original input cards and any errors that were encountered with them. When set to OFF, MFFTP only prints the output from the FTP client and server.
Parent topic: Configuring the MFFTP Utility
Related concepts
Major Features of the MFFTP Utility


MFFTP DD Statements

MFFTP requires the following DD statement:

INPUT
Defines the command that will be sent to the native FTP client together with the actual FTP commands.

MFFTP will use the following DD statements, if present:

OUTPUT
Specifies the preferred destination of all output including, for example, messages from MFFTP and the ftp client.
SYSPRINT
This can be used as an alternative to OUTPUT DD statement, to define preferred output destinations.
SYSFTPD
As on the mainframe. Only the keyword values described in the LOCSITE command are supported.
NETRC
As on the mainframe. This file, or in-stream data contains some login and initialization information. It is used to hide the login details in the JCL job card.
ENVVAR
Use this to code most of the environment variables, one per line. It overrides any values set at system level in Enterprise Server.
Note: This is especially useful if you need to set MFFTP_KEEP to Y to resolve a problem when the same variable is set to N at system level.
Note: If neither OUTPUT nor SYSPRINT is present, a SYSOUT file is dynamically allocated to show the messages as well as display them in the console.

The default record length of OUTPUT and SYSPRINT is 133 characters. This may be overwritten with the variables MFFTP_OUTPUT_LRECL and MFFTP_SYSPRINT_LRECL, respectively. These variables accept a numeric value of up to 512.

Parent topic: Configuring the MFFTP Utility


Input and Output Temporary Files

MFFTP reads the input stream and creates a control file. It then invokes the appropriate FTP program, passes the control commands to it and redirects the output to a file, which is then parsed. These input and output files are created in the default data directory and are removed at the end of the task.

The naming conventions for these temporary input and output files are:

ftpxxxxx.snnn.ip and ftpxxxxx.snnn.op

Where:

  • xxxxx is the JES job number where MFFTP is running
  • nnn is the step number within the job
  • ip indicates this is the input file
  • op indicates this is the output file

This mechanism enables concurrent execution of multiple instances of MFFTP. The file names of the temporary files are unique because of the use of the job number and step number.

To override the location of these temporary files, set the environment variable MFFTP_TEMP_DIR.

To use the name of the enterprise server instance as a prefix in the filenames of these files, set MFFTP_PREFIX to Y. This helps make the files unique if several enterprise server instances are sharing the same MFFTP_TEMP_DIR location.

To keep these files after the end of the task for documentation, debugging or other purposes, optionally set the environment variable MFFTP_KEEP.

Parent topic: Configuring the MFFTP Utility


Configuring the End-of-Line Marker

The mainframe FTP appends an end-of-line marker to each record. FTP clients on distributed platforms do not do this as they have no concept of a record.

An instruction to append this end-of-line marker can be sent to MFFTP when issuing a PUT command.

By default, no marker is added. You can set it either at the job step level using the ENVVAR DD statement or at server level using the following environment variable:

MFFTP_SENDEOL=xxxx

Where xxxx equals one of the following:

NONE
Adds nothing
CRLF
Adds a carriage return and a line feed (x’0D0A’)
CR
Adds a carriage return (x'0D')
LF
Adds a line feed (x’0A’)

You can also use the LOCSITE command to set the end-of-line marker. In this case, the variable name is either SBSENDEOL or MBSENDEOL, and the supported values are NONE, CRLF, CR, or LF. For example:

LOCSITE SBSENDEOL=CRLF

The LOCSITE command overwrites any other environment settings and may be varied during a session. This allows you to transfer one file with a CRLF and the next one - without it.

If you use an SBSENDEOL or an MBSENDEOL followed by a space, the variable can be placed in the SYSFTPD file.

Note: If SENDEOL is specified, the original physical file is not transferred. Instead, a copy of the file is made with the name ftpxxxxx.snnn.eol.zzzz (where xxxxx is the JES job number, nnn is the step number and zzzz is a sequence starting at 1 for this invocation of MFFTP). This file contains the appropriate end-of-line characters and is the file that is transferred.

By default, when MFFTP terminates, this file is deleted. To keep the file, you need to set MFFTP_KEEP to Y. If SENDEOL is set to NONE and a GET is performed for a variable record file, the results are unlikely to be as expected, as the program has no way of determining the end of each record in the fetched file.

Parent topic: Configuring the MFFTP Utility


Configuring Error Codes

Once the FTP client program executes, MFFTP scans the output looking for standard FTP responses. These take the form of 3-digit codes – for example, 331 which means the user id is correct but a password is required. Based on these codes, MFFTP sets the JCL condition code to either 0 for no errors or 4 for one or more errors.

Generally, error 332 and the codes in the 4nn and 5nn range are treated as errors.

If no messages are found, this indicates that the client was unable to connect to the server and the return code is set to 8.

If the messages which are predefined as errors do not meet your needs, you can change them using the user-configurable module, MFFTPURR. Each message is given a “pass” or “fail” rating which you can change and compile. If an MFFTPURR load module is found, its definitions will be used instead of the default ones.

Parent topic: Configuring the MFFTP Utility


Configuring the Text of Messages

The text of each message is determined by the FTP server in use rather than by MFFTP, and varies depending on the server implementation. When checking the pass or fail status of each message, another user-configurable module, MFFTPMSG, is available to alter the text of the message.

MFFTPMSG provides an example of how to replace the text of the message identified by code 230 with the simple text “User logged on”. Replacing the text in this way can be useful when you want to hide the name of the user. As with MFFTPURR, the load module is used, if located.

MFFTPMSG and MFFTPURR are sample programs shipped with the product in the src directory of the <install-dir> directory. If you want to use any of these modules, you need to compile them and put them in a location where they can be loaded by the run-time system - on the PATH defined as the ‘JES Program Path’ in the definition of the enterprise server instance.

Parent topic: Configuring the MFFTP Utility


Running the MFFTP Utility

The following is a sample JCL job that executes MFFTP:

//MFFTP01  JOB 'MFFTP TEST',CLASS=A,MSGCLASS=A
//*
//* Upload an MVS dataset
//*
//STEP1 EXEC PGM=MFFTP,PARM='my.ftp.server'
//SYSOUT DD  SYSOUT=*
//OUTPUT DD  SYSOUT=*
//INPUT  DD *
anonymous/test
cd MFFTP_TEST
put MFI01.MFFTP.FBFILE.TOUPLD MFFTP01.txt
locsite recfm=fb lrecl=10
locstat
;
get +
MFFTP01.txt MFI01.FTPDATA.FBFILE (rep
MFFTP_VARS
quit
/*
//ENVVAR  DD *
MFFTP_CLIENT=FTP
MFFTP_KEEP=Y
MFFTP_TIME=L
/*
//*

When this JCL is submitted, assuming there are no errors, you should see messages in the Enterprise Server console similar to the ones in When FTP is the Transport Client (MFFTP_CLIENT=FTP).

  • When FTP is the Transport Client (MFFTP_CLIENT=FTP)
    Example of messages output when operating with the MFFTP_CLIENT set to FTP.
  • When Using a Third Party as the Transport Client (MFFTP_CLIENT=USER)
    Output when operating with the MFFTP_CLIENT set to USER.
Parent topic: Micro Focus FTP Utility MFFTP
Related concepts
Specifying Environment Variables


When FTP is the Transport Client (MFFTP_CLIENT=FTP)

When the JCL provided in Running MFFTP is submitted and there are no errors, you should see messages in the Enterprise Server console similar to the ones below:

141211 15545316      10472 EDMFFTP  JCLCM0188I JOB01158 MFFTP01  JOB  STARTED 15:54:52
141211 15545356      10472 EDMFFTP  Micro Focus FTP Utility V3.00.09  (32 bit) Created: 26Nov2014 10:02 15:54:53
141211 15545376      10472 EDMFFTP  ftp -s:"C:\data\example\EDMFFTP\DATA\ftp01158.s001.ip" > "C:\data\example\EDMFFTP\DATA\ftp01158.s001.op" 2>&1 15:54:53
141211 15545776      10472 EDMFFTP  JCLCM0182I JOB01158 MFFTP01  JOB  ENDED   - COND CODE 0000 15:54:57

The output from this job is similar to the following:

                Micro Focus FTP Utility V3.00.09  (32 bit) Created: 26Nov2014 10

INFO..............: V3.00.09  (32 bit) Created: 26Nov2014 10:02
INFO..............: MFFTP_CLIENT set to "FTP"
INFO..............: MFFTP_TIME set to "L"
INFO..............: Using user ftp error code checking module (MFFTPURR)
INFO..............:
INFO..............: Exec parm is "my.ftp.server".
INFO..............: 1st parm "my.ftp.server" used as remote host.
WARNING...........: Other exec parm options ignored
FTP Input.........: C:\data\example\EDMFFTP\DATA\ftp01158.s001.ip
FTP Output........: C:\data\example\EDMFFTP\DATA\ftp01158.s001.op
FTP EOL temp file.: C:\data\example\EDMFFTP\DATA\ftp01158.s001.eol
FTP GET temp file.: C:\data\example\EDMFFTP\DATA\ftp01158.s001.wk1
INFO..............: SYSFTPD not found. Trying to work without it.
INFO..............: NETRC not found. Trying to work without it.
INPUT (data)......: anonymous/****
INFO..............: Assuming the above record is the userid & password.
INPUT (data)......: cd MFFTP_TEST
INPUT (data)......: put MFI01.MFFTP.FBFILE.TOUPLD MFFTP01.txt
INPUT (data)......: locsite recfm=fb lrecl=10
INPUT (data)......: locstat
LOCSTAT...........: The following options are in effect:
LOCSTAT...........:     - blksize=6233 from hard coded DEFAULTS
LOCSTAT...........:     - lrecl=10 from LOCSITE command
LOCSTAT...........:     - recfm=FB from LOCSITE command
LOCSTAT...........:     - space_units=TRK from hard coded DEFAULTS
LOCSTAT...........:     - primary_space_units=1 from hard coded DEFAULTS
LOCSTAT...........:     - secondary_space_units=1 from hard coded DEFAULTS
LOCSTAT...........:     - volume_serial=000000 from hard coded DEFAULTS
LOCSTAT...........:     - sendeol=NONE from hard coded DEFAULTS
LOCSTAT...........:     - dataconn=NONE from hard coded DEFAULTS
LOCSTAT...........:     - trailingblanks=TRUE from hard coded DEFAULTS
INPUT (comment)...: ;
INPUT (data)......: get +
INFO..............: Continuation marker found. Getting next record.
INPUT (data)......: MFFTP01.txt MFI01.FTPDATA.FBFILE (rep
WARNING...........: "MFI01.FTPDATA.FBFILE" already exists
WARNING...........:   and will be overwritten.
INPUT (data)......: MFFTP_VARS
MFFTP Variable....: MFFTP_ABCODE=(not_set)
MFFTP Variable....: MFFTP_ABEND=(not_set)
MFFTP Variable....: MFFTP_CHECK_221=(not_set)
MFFTP Variable....: MFFTP_CLIENT=FTP
MFFTP Variable....: MFFTP_DATACONN=(not_set)
MFFTP Variable....: MFFTP_DEBUG=(not_set)
MFFTP Variable....: MFFTP_ECHO_INPUT=(not_set)
MFFTP Variable....: MFFTP_EPSV=(not_set)
MFFTP Variable....: MFFTP_EXIT_EQUALS=(not_set)
MFFTP Variable....: MFFTP_KEEP=Y
MFFTP Variable....: MFFTP_KEEP_IP=(not_set)
MFFTP Variable....: MFFTP_OUTPUT_LRECL=(not_set)
MFFTP Variable....: MFFTP_PREFIX=(not_set)
MFFTP Variable....: MFFTP_RETCODE=(not_set)
MFFTP Variable....: MFFTP_SENDEOL=(not_set)
MFFTP Variable....: MFFTP_SFTP_AUTH=(not_set)
MFFTP Variable....: MFFTP_SFTP_CONNECT_TIMEOUT=(not_set)
                Micro Focus FTP Utility V3.00.09  (32 bit) Created: 26Nov2014 10

MFFTP Variable....: MFFTP_SFTP_ERRLVL=(not_set)
MFFTP Variable....: MFFTP_SFTP_IDLE_TIMEOUT=(not_set)
MFFTP Variable....: MFFTP_SYSPRINT_LRECL=(not_set)
MFFTP Variable....: MFFTP_TEMP_DIR=(not_set)
MFFTP Variable....: MFFTP_TIME=L
MFFTP Variable....: MFFTP_TRANSLATE_SAFETY=(not_set)
MFFTP Variable....: MFFTP_UFLAG=(not_set)
MFFTP Variable....: MFFTP_USRMSG=(not_set)
MFFTP Variable....: MFFTP_USR_FTP_PGM=(not_set)
MFFTP Variable....: MFFTP_VERBOSE_OUTPUT=(not_set)
MFFTP Variable....: MF_CHARSET=A
MFFTP Variable....: MFALLOC_LOC=C:\data\example\EDMFFTP\DATA
MFFTP Variable....: MFSYSCAT=C:\data\example\EDMFFTP\CATALOG.DAT
MFFTP Variable....: ES_SERVER=EDMFFTP
INPUT (data)......: quit
OUTPUT............: ftp> Connected to my.ftp.server.
OUTPUT............: open my.ftp.server
OUTPUT............: 220 Microsoft FTP Service
OUTPUT............: User (my.ftp.server:(none)):
OUTPUT............: 331 Password required for user
OUTPUT............:
OUTPUT............: 230 User logged in
OUTPUT............: ftp> cd MFFTP_TEST
OUTPUT............: 250 CWD command successful.
OUTPUT............: ftp> Local file Remote file put
OUTPUT............: C:\data\example\EDMFFTP\DATA\MFI01.MFFTP.FBFILE.TOUPLD.DAT
OUTPUT............: MFFTP01.txt
OUTPUT............: 200 PORT command successful.
OUTPUT............: 150 Opening ASCII mode data connection for MFFTP01.txt.
OUTPUT............: 226 Transfer complete.
OUTPUT............: ftp: 20 bytes sent in Seconds Kbytes/sec.
OUTPUT............: ftp> 0.350.06Local directory now C:\data\example\EDMFFTP\DAT
OUTPUT............: ftp> lcd "C:\data\example\EDMFFTP\DATA"
OUTPUT............: Remote file Local file get
OUTPUT............: MFFTP01.txt
OUTPUT............: C:\data\example\EDMFFTP\DATA\MFI01.FTPDATA.FBFILE.DAT
OUTPUT............: 200 PORT command successful.
OUTPUT............: 150 Opening ASCII mode data connection for MFFTP01.txt(20 by
OUTPUT............: 226 Transfer complete.
OUTPUT............: ftp: 20 bytes received in Seconds Kbytes/sec.
OUTPUT............: ftp> 0.0020.00bye
OUTPUT............: 221
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.ip
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.op
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.wk1
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.mget.ip
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.mget.log
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.mget.ip
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.mget.log
INFO..............: Start............15:54:53.48
INFO..............: FTP Start........15:54:53.74
INFO..............: FTP End..........15:54:57.44
INFO..............: End..............15:54:57.45
INFO..............: Elapsed run time.   3.97 seconds
INFO..............: Elapsed FTP time.   3.70 seconds
Parent topic: Running the MFFTP Utility
Related concepts
When Using a Third Party as the Transport Client (MFFTP_CLIENT=USER)


When Using a Third Party as the Transport Client (MFFTP_CLIENT=USER)

The precise output depends on the client being used and what is coded within the module specified by MFFTP_USR_FTP_PGM, so no example is provided. The output will be similar to that which is provided in the example when FTP is the client - see When FTP is the Transport Client (MFFTP_CLIENT=FTP) . The lines prefixed with “OUTPUT” are from the client and may be different. The others, for example “INPUT” and “INFO”, will be the same as they are generated by MFFTP.

Parent topic: Running the MFFTP Utility
Related concepts
When FTP is the Transport Client (MFFTP_CLIENT=FTP)


Writing a Module to Support a Third Party FTP Client

By default, MFFTP uses the host's default FTP client for transfers. To support a third party client - for example, to provide FTPS support - it must be possible to invoke the client from a standard command line. As there could be an infinite number of variations of the commands to invoke a third party client, you need a user-written module to generate and invoke them.

The following sections describe how to configure MFFTP to invoke a third party client, the parameter block that will be passed to the user module, and what is expected of it.

  • MFFTP Invoking a Third Party Client
    MFFTP environment variables required to invoke a third party FTP client.
  • The Parameter Block
    Copybook code for the parameter block that is passed to the user module.
  • MFFTP Processing the User Module
    Requirements for writing a user module.
Parent topic: Micro Focus FTP Utility MFFTP


MFFTP Invoking a Third Party Client

You need to set the following two environment variables to invoke the client:
  • Configure MFFTP to use a third party program.
    MFFTP_CLIENT=USER

  • A user-written module which is specified using MFFTP_USR_FTP_PGM invokes the third party program.

    MFFTP_USR_FTP_PGM=module

    This configures MFFTP to call the specified module, that will invoke the third part client.

If MFFTP-CLIENT is set to USER, MFFTP_USR_FTP_PGM must also be set and must name a module that is accessible to the batch process. If these conditions are not met, MFFTP aborts after validating the control cards.

Parent topic: Writing a Module to Support a Third Party FTP Client
Related concepts
The Parameter Block
MFFTP Processing the User Module


The Parameter Block

The code below is from the copybook MFUSRPRM.CPY. It describes the parameter block that is passed to the user module. The copybook is located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib directory. See the comments in the code for descriptions of each field:

      *===============================================================
      *   Copyright (C) 2007-2015 Micro Focus Limited.
      *   All rights reserved.
      *===============================================================

      *****************************************************************
      * Data items related to the module specified by MFFTP_USR_PGM   *
      *                                                               *
      * (tag)-usr-ftp-function-init                               *
      *   Function to be performed set as follows:                    *
      *   if (tag)-usr-ftp-function-init                          *
      *      used to cause the module to be loaded to ensure it exists*
      *   if (tag)-usr-ftp-function-call                          *
      *      normal call                                              *
      * (tag)-usr-ftp-return-code                                 *
      *   Indicate result of the call                                 *
      *   set (tag)-usr-ftp-ok true on an INIT call or if a       *
      *       normal call was deemed successful. The calling routine  *
      *       will scan the output to determine if the call to the    *
      *       FTP client was successful                               *
      *   set (tag)-usr-ftp-fail true if this module determines   *
      *       that there was a problem and that the calling module    *
      *       should not check the output                             *
      * (tag)-usr-ftp-ip-file-data.                               *
      *   Contains the length and fully qualified name of the file    *
      *   holding the normalised FTP control statements. This may be  *
      *   used directly or read to created an edited version as input *
      *   to the FTP client                                           *
      *    (tag)-usr-ftp-ip-name-len                              *
      *      actual length of the data in (tag)-usr-ftp-ip-name   *
      *    (tag)-usr-ftp-ip-name                                  *
      *      actual file name of the file holding the normalised FTP  *
      *      control statements                                       *
      * (tag)-usr-ftp-op-file-data.                               *
      *   Contains the length and fully qualified name of the file    *
      *   to hold the output from the FTP client that will be checked *
      *   (if appropriate) and printed by the calling routine. This   *
      *   may be the actual output from the FTP client or this        *
      *   routine may write an edited version here, for example to    *
      *   remove sensitive information.                               *
      *    (tag)-usr-ftp-op-name-len                              *
      *      actual length of the data in (tag)-usr-ftp-op-name   *
      *    (tag)-usr-ftp-op-name                                  *
      *      actual file name of the file to hold the output from the *
      *      FTP client (actual or edited)                            *
      * (tag)-usr-ftp-tmp-file-data.                              *
      *   Contains the length and the name of a directory that may be *
      *   used as a work are to hold temporary files.                 *
      *    (tag)-usr-ftp-tmp-name-len                             *
      *      actual length of the data in (tag)-usr-ftp-tmp-nam   *
      *    (tag)-usr-ftp-tmp-name                                 *
      *      The name of a directory that may be used to create       *
      *      temporary files, for example an edited input file or the *
      *      output from the FTP client before it is edited           *
      *****************************************************************
      *                                                               *
       01  (tag)-mfftp-usr-ftp-parm.
         05  (tag)-usr-ftp-function                pic x(1).
           88  (tag)-usr-ftp-function-init         value '0'.
           88  (tag)-usr-ftp-function-call         value '1'.
         05  (tag)-usr-ftp-return-code             pic x(1).
           88  (tag)-usr-ftp-ok                    value '0'.
           88  (tag)-usr-ftp-fail                  value '1'.
         05  (tag)-usr-ftp-msg1                    pic x(64).
         05  (tag)-usr-ftp-msg2                    pic x(64).
         05  (tag)-usr-ftp-pass-ip-data.
           10  (tag)-usr-ftp-pass-ip-fname-len     pic 9(3).
           10  (tag)-usr-ftp-pass-ip-fname         pic x(512).
         05  (tag)-usr-ftp-pass-op-data.
           10  (tag)-usr-ftp-pass-op-fname-len     pic 9(3).
           10  (tag)-usr-ftp-pass-op-fname         pic x(512).
         05  (tag)-usr-ftp-user-ip-data.
           10  (tag)-usr-ftp-user-ip-fname-len     pic 9(3).
           10  (tag)-usr-ftp-user-ip-fname         pic x(512).
         05  (tag)-usr-ftp-user-op-data.
           10  (tag)-usr-ftp-user-op-fname-len     pic 9(3).
           10  (tag)-usr-ftp-user-op-fname         pic x(512).
         05  (tag)-usr-ftp-temp-data.
           10  (tag)-usr-ftp-temp-fname-len        pic 9(3).
           10  (tag)-usr-ftp-temp-fname            pic x(512).
Parent topic: Writing a Module to Support a Third Party FTP Client
Related concepts
MFFTP Invoking a Third Party Client
MFFTP Processing the User Module


MFFTP Processing the User Module

The parameter block specified in the topic The Parameter Block is passed to the user module.

As a minimum, set the return code in the INIT function and return the call. This enables the user module to call MFFTP. If the user module requires any other initialization, you need to specify the required parameters at this point.

In the CALL function, the user module should do its normal processing. The module passes four unique filenames, two of which are required by MFFTP and two that might be used by this module.

While it is not a requirement to use these names, they must be unique within the Enterprise Server environment, allowing concurrent execution without locking files.

The “PASS-IP” (ftpxxxxx.snnn.ip) is a dynamically created text file which contains the control cards that MFFTP has checked and performed any reformatting on. As a minimum, the file should include the following four records:

  • Record 1: The open statement which holds the target server and potentially the port number. The format is “open”, target-server, port (if present) each separated by a space.
  • Record 2: The user id
  • Record 3: The password
  • Record 4: "bye"

The user module writes any output from the client to this file, as it is this file that MFFTP writes to the designated print file. The client could write directly to this file or to an intermediate file, and the user module can edit the output, for example, to mask any sensitive information such as the user id or the password.

Two sample modules are provided:

  • MFWSFTP. This uses the third-party client called WS_FTP Pro and shows a few examples of “editing” that can be done before actually invoking the client. It also shows how to invoke the client.
  • MFWINFTP. This uses the Windows FTP client. This is essentially the same as setting MFFTP_CLIENT=FTP.

The two sample modules can be found in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src$COBDIR/src/enterpriseserver/exit directories.

Different clients are likely to have different requirements. Micro Focus recommends that, if you wish to use this option, you either start from scratch by creating new modules or make a copy of one of the sample modules rather than modify the original files.

To access any of the environment variables, you need to call MFFTP12 rather than use the DISPLAY ENVIRONMENT-NAME / ACCEPT ENVIRONMENT-VALUE method. This is because if the variable was set using the ENVVAR DD statement, it does not exist within the environment space.

To retrieve any variable, call MFFTP12 as follows:

01  ws-var-name                             pic x(32).
01  ws-var-value                            pic x(256).

move "MFFTP_var-name" to ws-var-name.
call "MFFTP12" using ws-var-name
                     ws-var-value
end-call

After the call, if MFFTP locates the variable, it is in the second parameter.

If the value in the first parameter is not an MFFTP environment variable, the first byte of the second parameter is set to x’FF’.

Parent topic: Writing a Module to Support a Third Party FTP Client
Related concepts
MFFTP Invoking a Third Party Client
The Parameter Block


Enterprise Server Reference

  • Administration and Configuration Commands
  • Error Messages
  • User Exits
  • MQ Listener and Writer Types
    Describes MQ listener and writer types used by Enterprise Server.
Parent topic: Enterprise Server


Administration and Configuration Commands

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.
  • casstart
    Starts an enterprise server.
  • casstop
    Stops 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


mfds

Manages the Directory Server.

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:

/c
Install the Directory Server as a Windows service, and when it runs, show the debug information console. Once you have issued the mfds command with this parameter, you start Directory Server using the Windows Control Panel.
/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.

/i
Install the Directory Server as a Windows service, and when it runs, do not show the debug information console. Once you have issued the mfds command with this parameter, you start Directory Server using the Windows Control Panel.
/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.

/u
Uninstall Directory Server as a Windows service
/v
Show version information for Directory Server
/x [repository type]
1 = file:///
5 = XML
[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:

Note: Issuing an mfds command with any of the parameters /c, /e, /i, /l, /m, /u, /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..

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

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

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

  • 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

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.

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

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

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

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

  • 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

Resolution:

Enter a value of 5 or greater.

Parent topic: Directory Server Error Messages 21 to 40


MDS0022E Minimum journal size is 32 KB

Resolution:

Enter a value of 32 (KB) or greater.

Parent topic: Directory Server Error Messages 21 to 40


MDS0023E Insufficient memory for this operation

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

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

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

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

  • 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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\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

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:

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

  • 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

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

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

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

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

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

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

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

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

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

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

  • 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.
  • MDS0090E TN3270 listener port must have a valid value
    When adding an MSS-enabled ES server, a TN3270 listener is defined by default. This default listener has not had a port value defined for it, or the defined value is outside the standard TCP port value range.
  • 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

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

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

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


MDS0090E TN3270 listener port must have a valid value

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

  • CASAM error messages
    Server management error messages
  • CASBJ Error Messages
    Batch Job error messages
  • CASCD Error Messages
    Console Daemon error messages.
  • CASCF Error Messages
    Configuration support error messages.
  • CASCL Error Messages
    Client management error messages
  • CASCS Error Messages
    Communications error messages.
  • CASCT Error Messages
    Supplied Transactions 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
  • CASIP Error Messages
    IMS message processing error messages.
  • CASJC Error Messages
    Journal Control error messages
  • CASKC Error Messages
    Task control error messages.
  • CASMG Error Message
    Error message file error message.
  • CASMQ Error Messages
    Trigger monitor error messages
  • CASMS Error Messages
    Basic Mapping Support error messages
  • CASOP Error Messages
    User Messages to Console
  • CASPC Error Messages
    Program Control error messages
  • CASRA Error Messages
    Resource Definition API error messages
  • CASRB Error Messages
    Miscellaneous error messages
  • CASRD Error Messages
    Resource Definition error messages.
  • CASRM Error Messages
    Resource Manager Control error messages
  • CASSE Error Messages
    Security error messages
  • CASSI Error Messages
    System initialization error messages.
  • CASSP Error Messages
    Syncpoint and Recovery Services error messages.
  • CASST Error Messages
    Server termination error messages.
  • CASTM Error Messages
    System Termination error messages
  • CASTS Error Messages
    TSC Service process error messages
  • CASXB Error Messages
    BMS Macro Processor error messages
  • CASXO Error Messages
    Transaction Manager error messages.
Parent topic: Error Messages


CASAM error messages

0001I Development region region-name created successfully
The %1$s development region has been successfully created.
  • System action: None
  • User response: None
  • Destination: standard error
  • Module: dfhcrtrg
0002F Region region-name not created
The request to create the region was not successful.
  • System action: The request is rejected.
  • User response: Check previous messages for cause of error. Correct the problem and retry the request.
  • Destination: standard error
  • Module: dfhcrtrg
0003E Too many arguments, maximum is 2
Too many arguments were specified, the maximum permitted is 2.
  • System action: The request is rejected
  • User response: Retry the request with the correct number of arguments
  • Destination: standard error
  • Module: dfhcrtrg
0004E Unrecognized option option-value
The specified option is not valid
  • System action: The request is rejected
  • User response: Retry the request with a valid option
  • Destination: standard error
  • Module: dfhcrtrg
0005E region-name is not a valid region name
region-name cannot be used as a region name. A region name must be alphanumeric, 4-8 characters long, and not a reserved system directory name
  • System action: The request is rejected
  • User response: Retry the request with a valid region name
  • Destination: standard error
  • Module: dfhcrtrg
0006E Development region region-name already exists
An attempt was made to create a development region that already exists
  • System action: The request is rejected
  • User response: Retry the request with a unique region name
  • Destination: standard error
  • Module: dfhcrtrg
0007E Development region region-name requires group of same name
When creating a development region the name must match that of an existing user group
  • System action: The request is rejected
  • User response: Create a user group of the same name and retry
  • Destination: standard error
  • Module: dfhcrtrg
0008S Failed to create directory directory-name, reason return-code
The OS returned a return code of return-code for the request to create the specified directory.
  • System action: The request is rejected
  • User response: None
  • Destination: standard error
  • Module: dfhcrtrg
0010S Region base path path-name does not exist
A specific path to the region has been specified but does not exist.
  • System action: The request is rejected
  • User response: Create the path or correct the configuration file dfhtx.cfg
  • Destination: standard error
  • Module: dfhcrtrg
0011S region-name is the default region name and cannot be created
region-name is the default or "global" region. It uses the base directory structure and therefore cannot be created with this utility. It is recommended that the global region (i.e. its directory structure) not be used for normal operations.
  • System action: The request is rejected
  • User response: Select another name for the region.
  • Destination: standard error
  • Module: dfhcrtrg
0012I Production region region-name created successfully
The production region has been successfully created.
  • System action: None
  • User response: None
  • Destination: standard error
  • Module: dfhcrtrg
0013I Production region region-name has been changed to development
The production region has been changed to development.
  • System action: None
  • User response: None
  • Destination: standard error
  • Module: dfhcrtrg
0014I Region base directory for region-name is region-base
The region-name is the region's base directory for region-base.
  • System action: None
  • User response: None
  • Destination: standard error
  • Module: dfhcrtrg
0015E Production region region-name already exists
An attempt was made to create a production region that already exists
  • System action: The request is rejected
  • User response: Retry the request with a unique region name
  • Destination: standard error
  • Module: dfhcrtrg
0017I Defaulting to a region-name region for region-type
No command line parameters were specified so the region was created as region-type by default. A production region is created unless the system locates a development configuration file, the default is then a development region.
  • System action: None
  • User response: None
  • Destination: standard error
  • Module: dfhcrtrg
1001W CFMT file (or dataset) name not supplied
The file name to action was not supplied. Usage is CFMT {fn} {file-name}
  • System action: None
  • User response: Correct the input and resubmit the request
  • Destination: Terminal
  • Module: dfhzcfmt
1002I CFMT Usage {fn} {file name} where fn={OPen,CLose,ENable,DIsable,INquire,NAme}
No input was supplied with the transaction. This message documents the required parameters. The user should enter the transaction ID, function, and file name. The function may be "open", "close", "enable", "disable", "inquire" or "name". The transaction considers only the first two letters of the function parameter to determine its action.
  • System action: None
  • User response: None
  • Destination: Terminal
  • Module: dfhzcfmt
1003I Zero length input for CFMT at terminal-id, user user-id
The transaction CFMT started on the terminal but there was no input data. The request executed on terminal terminal-id where user user-id was signed on.
  • System action: None
  • User response: Correct the input and resubmit the request
  • Destination: Terminal
  • Module: dfhzcfmt
1004W Invalid CFMT initiation at terminal-id, user user-id
The transaction CFMT started on the terminal but the start was not a valid start. The request executed on terminal terminal-id where user user-id was signed on.
  • System action: None
  • User response: Correct the transaction initiation and resubmit the request
  • Destination: Terminal
  • Module: dfhzcfmt
1005I CFMT - File file-id opened successfully; terminal-id, user user-id
The request to open the file was successful.
  • System action: The file was opened
  • User response: None
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcfmt
1006I CFMT - File file-id closed successfully; terminal-id, user user-id
The request to close the file was successful.
  • System action: The file was closed
  • User response: None
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcfmt
1007I CFMT - File file-id enabled successfully; terminal-id, user user-id
The request to enable the file was successful.
  • System action: The file was enabled
  • User response: None
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcfmt
1008I CFMT - File file-id disabled successfully; terminal-id, user user-id
The request to disable the file was successful.
  • System action: The file was disabled
  • User response: None
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcfmt
1009I CFMT - File file-id is open-status and enable-status; terminal-id, user user-id
The inquire request was successful. The status of file open-status and enable-status. If an unexpected CVDA value is returned for either of these statuses, the actual numeric status will be reported.
  • System action: None
  • User response: None
  • Destination: Terminal
  • Module: dfhzcfmt
1010W CFMT invalid request (request) for file file-id at terminal-id, user user-id
The request for the file was not recognized. It may be OPen, CLose, ENable, DIsable, INquire or NAme. Only the first two characters of the request are examined by the program. The request is not case sensitive.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Destination: Terminal
  • Module: dfhzcfmt
1011W CFMT file file-id not found; terminal-id, user user-id
The file was not found. The file name is case sensitive.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Destination: Terminal
  • Module: dfhzcfmt
1012E CFMT request not authorized for file file-id at terminal-id, user user-id
The request for the file is not authorized.
  • System action: The request is ignored
  • User response: Correct the input or consult with the security administrator.
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcfmt
1013E CFMT file file-id unexpected response (eibresp); terminal-id, user user-id
The requested action for the file resulted in an unexpected API response.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Destination: Terminal
  • Module: dfhzcfmt
1014W CFMT illogic response for request to file file-id; terminal-id, user user-id
The requested action for the file resulted in an illogic API response. The requested transition is not logical, for example, an open request for a file that is already open.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Destination: Terminal
  • Module: dfhzcfmt
1015I CFMT file file-id DSNAME (DSNAME)
The DSNAME associated with the file is displayed.
  • System action: None.
  • User response: None.
  • Destination: Terminal
  • Module: dfhzcfmt
1016I CFMT function function completed. error-count error(s) encountered. See CEBR.
The requested action has completed. The number of errors is shown.
  • System action: None.
  • User response: Use the CEBR transaction to view the log.
  • Destination: Terminal
  • Module: dfhzcfmt
1017E CFMT file file-id IOERR (eibresp-1/eibresp-2); terminal-id, user user-id
The requested action for the file resulted in an IOERR.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Destination: Terminal
  • Module: dfhzcfmt
1020W Error opening file (file-id) group (group-id) - status=(file-status-1, file-status-2)
A file marked as Start Open / Enabled could not be opened in system initialization due to the I/O error specified.
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.
Common values for status:
Status | Reason | Action
3005 | file not found | Correct file name in FCT or create file with CFCR if necessary.
9065 | file locked | Ensure that another program has not opened the file exclusively.
9124 | comms error | Make sure the Fileshare server is running and the correct CCI protocol is defined in the FHREDIR configuration file.
  • System action: The file will not be opened.
  • User response: Correct the error and open the file using the CFMT transaction.
  • Destination: Console
  • Module: dfhzplt
1030I CNCL Usage: CNCL {program-name}
No input was supplied with the transaction. This message documents the required parameters. The user should enter the transaction ID and program name.
  • System action: None
  • User response: None
  • Destination: Terminal
  • Module: dfhzcncl
1031I Zero length input for CNCL at terminal-id, user user-id
The transaction CNCL started on the terminal but there was no input data.
  • System action: None
  • User response: Correct the input and resubmit the request
  • Destination: Terminal
  • Module: dfhzcncl
1032W Invalid CNCL initiation at terminal-id, user user-id
The transaction CNCL started on the terminal but the start was not a valid start.
  • System action: None
  • User response: Correct the transaction initiation and resubmit the request
  • Destination: Terminal
  • Module: dfhzcncl
1033E Invalid cancel request at terminal-id, PPT entry found for program program-name, user user-id
The program name passed to CNCL was found as a PPT entry. The CPMT transaction should be used to issue NEWCOPY requests for CICS programs.
  • System action: None
  • User response: Use the CPMT transaction to release the CICS program.
  • Destination: Terminal
  • Module: dfhzcncl
1033E PPT entry found for program program-name not COBOL at terminal-id, user user-id
The program name passed to CNCL was found as a PPT entry which was not marked as a COBOL program. This transaction can only release COBOL programs.
  • System action: None
  • User response: Supply a valid program name or change the PPT definition.
  • Destination: Terminal
  • Module: dfhzcncl
1034E PPT entry found for program program-name not LOCAL at terminal-id, user user-id
The program name passed to CNCL was found as a PPT entry which was not a local program.
  • System action: None
  • User response: Supply a valid program name or change the PPT definition.
  • Destination: Terminal
  • Module: dfhzcncl
1035I CNCL request for program program-name issued at terminal-id, user user-id
The program release request was issued successfully.
  • System action: None
  • User response: None
  • Destination: Terminal
  • Module: dfhzcncl
1036W CNCL request for program program-name failed at terminal-id, user user-id
The program release request failed. This error will occur if the program was not actually in memory when the command was issued or logical cancel support is not enabled in the COBOL RTS.
  • System action: None
  • User response: None
  • Destination: Terminal
  • Module: dfhzcncl
1101W CKQC can only be run in multi-tasking mode to start an WebSphere MQ CKTI monitor
The region is currently running in single-tasking mode. The WebSphere MQ monitor may only be run in multi-tasking mode.
  • System action: None
  • User response: Restart CICS Option in multi-tasking mode, and reinvoke CKQC.
  • Destination: Terminal
  • Module: dfhzckqc
1102W Unexpected error (return-code) requesting CKTI
The CICS Option Process Requester returned an unexpected response.
  • System action: The CKTI monitor is not started.
  • User response: Retry the CKQC transaction. If the problem persists, contact Support.
  • Destination: Terminal
  • Module: dfhzckqc
1103W No initiation queue name given
To start an WebSphere MQ monitor, you need to supply an initiation queue name.
  • System action: The CKTI monitor is not started.
  • User response: Resubmit, specifying a queue name.
  • Destination: Terminal
  • Module: dfhzckqc
1104I Usage: CKQC STARTCKTI <initiation-queue>
To start an WebSphere MQ monitor via the LINK interface, you need to supply an initiation queue name.
  • System action: The CKTI monitor is not started.
  • User response: Resubmit, specifying a queue name.
  • Destination: Terminal
  • Module: dfhzckqc
1105W Invalid function key - use ENTER to accept data
The only keys that are recognized are: CLEAR, PF3 & ENTER.
  • System action: None
  • User response: Retry using a valid key.
  • Destination: Terminal
  • Module: dfhzckqc
1106E WebSphere MQ queue manager name not found. RC=return-code
The WebSphere MQ queue manager name cannot be found.
  • System action: None
  • User response: Check that WebSphere MQ has been configured correctly in the system initialization table.
  • Destination: Terminal
  • Module: dfhzckqc
1107I CKTI requested for initiation-queue
A request to start a CKTI has been initiated.
  • System action: CICS Option attempts to initialize an WebSphere MQ trigger monitor.
  • User response: Check console
  • Destination: Terminal
  • Module: dfhzckqc
2001W CPMT program or table name not supplied
The program name to action was not supplied. Usage is CPMT {fn} {program-name}.
  • System action: None
  • User response: Correct the input and resubmit the request
  • Destination: Terminal
  • Module: dfhzcpmt
2003I Zero length input for CPMT at terminal-id, user user-id
The transaction CPMT started on the terminal but there was no input data.
  • System action: None
  • User response: Correct the input and resubmit the request
  • Destination: Terminal
  • Module: dfhzcpmt
2004W Invalid CPMT initiation at terminal-id, user user-id
The transaction CPMT started on the terminal but the start was not a valid start.
  • System action: None
  • User response: Correct the transaction initiation and resubmit the request
  • Destination: Terminal
  • Module: dfhzcpmt
2005I CPMT - Program program-id newcopy; terminal-id, user user-id
The request to load a new copy of the program was successful.
  • System action: A new copy of the program is loaded.
  • User response: None
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcpmt
2006I CPMT - Program program-name phasein; terminal-id, user user-id
The request to load a new copy of %3$s by user %2$s at terminal %1$s was successful. The new copy will be used for all new requests.
  • System action: A new copy of the program is being phased in.
  • User response: None
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcpmt
2007I CPMT - Program program-name private; terminal-id, user user-id
The request to mark the program as private was successful.
  • System action:
  • User response: None
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcpmt
2008I CPMT - Program program-name shared; terminal-id, user user-id
The request to mark the program as shared was successful.
  • System action:
  • User response: None
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcpmt
2009I CPMT - Program program-name dplsubset; terminal-id, user user-id
The request to mark the program as dplsubset was successful.
  • System action:
  • User response: None
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcpmt
2010I CPMT - Program program-name fullapi; terminal-id, user user-id
The request to mark the program as fullapi successful.
  • System action:
  • User response: None
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcpmt
2011I CPMT - Program program-name cedf; terminal-id, user user-id
The request to mark the program as cedf was successful.
  • System action:
  • User response: None
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcpmt
2012I CPMT - Program program-name nocedf; terminal-id, user user-id
The request to mark the program as nocedf was successful.
  • System action:
  • User response: None
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcpmt
2013I CPMT - Program program-name is disabled; terminal-id, user user-id
The request to mark the program as disabled was successful.
  • System action:
  • User response: None
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcpmt
2014I CPMT - Program program-name is enabled; terminal-id, user user-id
The request to mark the program %3$s as enabled was successful.
  • System action:
  • User response: None
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcpmt
2016I Program program-name is not currently loaded
Program has not been loaded. The full name cannot be displayed until it has been accessed.
  • System action:
  • User response: Do a NEWCOPY or PHASEIN command and repeat this inquiry.
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcpmt
2018W CPMT invalid request (request) for program program-name at terminal-id, user user-id
The request for the program was not recognized. It may be OPen, CLose, ENable, DIsable, or INquire. Only the first two characters of the request are examined by the program. The request is not case sensitive.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Destination: Terminal
  • Module: dfhzcpmt
2019W CPMT program program-name not found; terminal-id, user user-id
The program was not found. The program name is case sensitive on some platforms.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Destination: Terminal
  • Module: dfhzcpmt
2020E CPMT request not authorized for program program-name at terminal-id, user user-id
The request for the program is not authorized.
  • System action: The request is ignored
  • User response: Correct the input or consult with the security administrator.
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcpmt
2021E CPMT program program-name unexpected response (eibresp); terminal-id, user user-id
The requested action for the program resulted in an unexpected API response.
  • System action: The request is ignored
  • User response: Correct the input and resubmit
  • Destination: Terminal
  • Module: dfhzcpmt
2023I CPMT - PPT for Program program-name was discarded; terminal-id, user user-id
The request to discard the PPT for program %3$s by user %2$s at terminal %1$s was successful.
  • System action:
  • User response: None
  • Destination: Terminal, CSMT td queue, and console
  • Module: dfhzcpmt
3000S Critical Event Manager storage error
The Event Manager Process encountered a local storage failure that was not recoverable.
  • System action: The Event Manager will be terminated.
  • User response: Correct the error and restart the region.
  • Destination: Console and standard error.
  • Module: casevmgr
3001I Event Manager exit enabled (exit-program-name)
The Event Manager Process loaded the user-defined exit.
  • System action: The Event Manager call the exit at appropriate points.
  • User response: None
  • Destination: Console and standard error.
  • Module: casevmgr
3002W Event Manager unable to load exit (exit-program-name)
The Event Manager Process was unable to load the user-defined exit.
  • System action: The Event Manager will ignore the exit.
  • User response: Check the exit specification and ensure it is on the search path.
  • Destination: Console and standard error.
  • Module: casevmgr
3005E Unable to parse filter string. expected "expected-value"; found "actual-value-found" - at end of "filter-string"
The event manager was unable to process the event filter string because it was badly constructed.
  • System action: Event manager will switch off event filtering for this exit and send all events without being filtered
  • User response: Check the filter string, and restart the server
  • Destination: Console and standard error.
  • Module: casevmgr
3006I Event Filter for (exit-name) has been enabled/disabled. Filter string: "filter-string"
Event manager has enabled/disabled the event filter for this exit.
  • System action: none
  • User response: none
  • Destination: Console and standard error.
  • Module: casevmgr
3007E Unexpected logic error in program when parsing the event filter string. Exit: "exit-name" / Filter string: "filter-string"
Event manager encountered a logic error when parsing the filter string for the specified exit.
  • System action: none
  • User response: contact Micro Focus Team
  • Destination: Console and standard error.
  • Module: casevmgr
3008E Illegal Type-id: "type-id-found". Max type-id: "max-type-id"
The type ID specified exceeds the maximum type ID.
  • System action: none
  • User response: check and correct the filter string
  • Destination: Console and standard error.
  • Module: casevmgr
3009E Illegal sub-type-id: "sub-type-id-found". Max sub-type-id: "max-sub-type-id"
The subtype ID specified exceeds the maximum subtype ID.
  • System action: none
  • User response: check and correct the filter string
  • Destination: Console and standard error.
  • Module: casevmgr
3010E Illegal id range: "id-lo" - "id-hi"
The ID range specified is invalid.
  • System action: none
  • User response: check and correct the filter string
  • Destination: Console and standard error.
  • Module: casevmgr
3011W Exit initialisation failed. Exit name: "exit-name"
The exit returned a return code specifying its initialisation failed.
  • System action: none
  • User response: check the exit to find out why initialisation of the exit failed
  • Destination: Console and standard error.
  • Module: casevmgr
3012E Initialisation to generate Windows Events from EMP failed.
EMP is unable to generate Windows events based on the events reported to EMP.
  • System action: none
  • User response: contact Micro Focus
  • Destination: Console and standard error.
  • Module: casevmgr
3013E Unable to register server as active server for Monitoring and Management. Monitoring and Management support disabled.
Event Manager is unable to register the server as an active server for Monitoring and Management.
  • System action: none
  • User response: contact Micro Focus
  • Destination: Console and standard error.
  • Module: casevmgr
3014E Unable to create Server Monitoring and Management shared memory. Monitoring and Management support disabled.
Event Manager is unable to create the shared memory region for Monitoring and Management
  • System action: none
  • User response: contact Micro Focus
  • Destination: Console and standard error.
  • Module: casevmgr
3015W Unable to unregister the server from active servers list for Monitoring and Management. Error Accessing registry
Event Manager is unable to unregister the server from the active servers for Monitoring and Management list.
  • System action: none
  • User response: contact Micro Focus
  • Destination: Console and standard error.
  • Module: casevmgr
3016I ES Monitoring and Management support enabled
The Monitoring and management support for this server has been enabled
  • System action: none
  • User response: none
  • Destination: Console and standard error.
  • Module: casevmgr
3017E ES Monitoring and Management unable to open performance registry key: "Registry key", RC=Return code for WIN API call "RegOpenKeyExA" . M & M disabled.
Event manager encountered an error opening the performance registry key
  • System action: none
  • User response: none
  • Destination: Console and standard error.
  • Module: casevmgr
3018E ES Monitoring and Management unable to get performance registry key: "Registry key\Registry value name", RC=Return code for WIN API call "RegQueryValueExA" .
Event manager encountered an error retrieving the performance registry key value
  • System action: M & M is disabled.
  • User response: Perform an install repair on your system.
  • Destination: Console and standard error.
  • Module: casevmgr
3019W ES Monitoring and Management retrieved unexpected value for "Registry key\Registry value name": actual=Actual value of registry key, expected Expected value of registry key.
Event manager retrieved an unexpected value for the performance registry key value. You may have performed a Windows install repair, which has reinstated a back-level registry entry.
  • System action: M & M may have been disabled.
  • User response: Perform an install repair on your system. You may also need to run a script file to effect additional repairs on the registry settings. This is called perfreg.cmd and is provided in NX\Base\SOURCE\ENTERPRISESERVER\Monitoring.
  • Destination: Console and standard error.
  • Module: casevmgr
3020E ES Monitoring and Management detected non-zero value for "Registry key\Registry value name". M & M disabled.
Event manager has detected that performance monitoring has been disabled.
  • System action: M&M is disabled.
  • User response: Use the registry editor program, regedit, to delete the key value or set it to 0. Check the "library" entry is pointing to the correct version of cas0perf.dll. Check the server's console.log file for monitoring and management messages. Shut down and restart your server.
  • Destination: Console and standard error.
  • Module: casevmgr
3021W ES Monitoring and Management unable to get value for "Registry key\Registry value name": Return code for WIN API call "RegQueryValueExA"
Event manager retrieved an unexpected return code when querying the performance registry key value. The performance counters may not have been loaded correctly.
  • System action: none
  • User response: Perform an install repair on your system. If this fails to restore performance monitoring, you will need to run the load counter utility, LODCTR. First, locate the file cas0psys.ini, which is in NX\Base\Bin. Then run this command: lodctr cas0psys.ini
  • Destination: Console and standard error.
  • Module: casevmgr
3022W ES Monitoring and Management detected incorrect value for "Registry key\Registry value name": Performance monitoring load module name
Event manager retrieved an unexpected value when querying the performance registry key value. Performance monitoring may not have been behave correctly.
  • System action: none
  • User response: Perform an install repair on your system. If this fails to restore performance monitoring, you will need update the registry key. This should have a value of NX\Base\Bin\cas0perf.dll, where NX" is the folder where you installed the product.
  • Destination: Console and standard error.
  • Module: casevmgr
3023E Error accessing file casglm.lck "return-code".
While trying to access the file casglm.lck an error occurred.
  • System action: none
  • User response: Check the return code, and contact your technical support.
  • Destination: Console and standard error.
  • Module: casmgr
TXAM1020W Error opening file (file-id) group (group-id) - status=(file-status-1,file-status-2)
A file marked as Start Open / Enabled could not be opened in system initialization due to the I/O 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 an RTS error.

Common values for status:

Status | Reason | Action
3005 | File not found | Correct file name in FCT or create file with CFCR if necessary.
9065 | File locked | Ensure that another program has not opened the file exclusively.
9124 | Comms error | Make sure the Fileshare server is running and the correct CCI protocol is defined in the FHREDIR configuration file.
  • System action: The file will not be opened.
  • User response: Correct the error and open the file using the CFMT transaction.
  • Destination: Console
  • Module: dfhzplt
Parent topic: Enterprise Server Error Messages


CASBJ Error Messages

Message | Description | Resolution
CASBJ0000I message | This is an ad hoc message for the JES subsystem | None
CASBJ0001I Batch Input Spool has been "cold-started" | An existing Input Spool Repository for this Server was not found and therefore a new one was created. The Input Spool Repository is effectively in a "cold start" condition. | None
CASBJ0002E JCL parser not available | The batch JCL parser is not available on this server | Correct the installation
CASBJ0003E JOBjob-number duplicates an existing job number | The Job Entry Subsystem generated a job number that duplicates an existing job number. | Retry the submission
CASBJ0004I JOBjob-number job-name class job-class, TYPRUN=type-run | The Job Entry Subsystem accepted the submitted job | None
CASBJ0005I Batch initiator started for job classes "job-classes" | The batch initiator was started an is available for processing MVS JCL and native batch scripts. Jobs will be selected from classes job-classes. | None
CASBJ0006I Batch initiator initialization started | The batch initiator process initialization started | None
CASBJ0007S Error return-code during initialization of server PCA | An error occurred whilst initializing the server's Process Control Area. The server will not complete its initialization. | Make sure that the region for which the server was to be started is running and retry.
CASBJ0008I Batch Input Spool has been "cold-started" | An existing Input Spool Repository for this Server was not found and therefore a new one was created. The Input Spool Repository is effectively in a "cold start" condition. | None
CASBJ0009I Batch initiator shutdown complete. | The batch initiator server process has shutdown normally. | None.
CASBJ0010E Batch Spool File Error; Status action-status. | The batch execution server failed trying to open the Spool reference file. The action and status are: action-status | Correct the problem with the spool file and retry
CASBJ0011E Batch Spool File Error; Status action-status. | The batch execution server failed trying to close the Spool reference file. The action and status are: action-status | Correct the problem with the spool file and retry
CASBJ0012I Batch Input Spool has been "cold-started" | An existing Input Spool Repository for this Server was not found and therefore a new one was created. The Input Spool Repository is effectively in a "cold start" condition. | None
CASBJ0013E Batch Spool File Error; Status action-status. | The batch execution server failed trying to open the Spool reference file. The action and status are: action-status | Correct the problem with the spool file and retry
CASBJ0014I JOBjob-number started | The batch initiator has started processing job-number | None
CASBJ0015I message | This reports informational messages from the JCL execution engine | None
CASBJ0016W message | This reports warning messages from the JCL execution engine | None
CASBJ0017E message | This reports error messages from the JCL execution engine | None
CASBJ0018S message | This reports severe error messages from the JCL execution engine | None
CASBJ0019U message | This reports unrecoverable error messages from the JCL execution engine | None
CASBJ0020I Batch printer initialization started | The batch printer process initialization started | None
CASBJ0021I Batch printer started for print output classes "output-classes" | The batch printer was started an is available for processing system output. Jobs will be selected from classes output-classes. | None
CASBJ0022I Batch printer definition-name: class(es) "print-classes" | The batch printer was started an is available for processing output. Job output will be selected from classes print-classes. | None
CASBJ0023I Batch initiator definition-name: class(es) "initiator-classes" | The batch initiator was started an is available for processing output. Jobs will be selected from classes initiator-classes. | None
CASBJ0024I Batch Printer: "printer-name" | The batch printer was started and will write to physical printer printer-name. | None
CASBJ0025E Printer not found: "printer-name" | The physical printer printer-name was not found. | Correct the printer name and retry the operation
CASBJ0026I Exit Module: "exit-module" | The batch printer is configured to use exit module exit-module. | None
CASBJ0027E Printer assignment failed. RC=return-code | Call to set assigned printer as the default for this processor failed with a return-code of return-code. | Correct the printer name and retry the operation
CASBJ0028E Load failed for exit Module: "exit-module" | The batch printer failed to load exit module exit-module. | Correct exit module name or location and restart printer
CASBJ0029I print-dataset-title on printer-name | The batch printer is printing "print-dataset-title" on printer printer-name | None
CASBJ0030E error-message | The batch print processor experienced the stated problem. | None
CASBJ0031E Printer open failed. RC=return-code | Call to open assigned printer failed with a return-code of return-code. | Correct the printer problem and retry the operation
CASBJ0032E Printer write failed. RC=return-code | Call to write to the assigned printer failed with a return-code of return-code. | Correct the printer problem and retry the job
CASBJ0033E Printer error accessing spool data: status-data | Print processor encountered an error accessing the spool data. The operation and status is status-data. | Correct the problem and retry the job
CASBJ0034I Printer process shutdown complete. | The print processor server process has shutdown normally. | None.
CASBJ0035I Console input request is pending.# | A job or service has requested input from the system console. | Reply to the request
CASBJ0036E job-number Spool purge processor not available# | Print processor could not locate the Spool purge processor. | Correct the problem and restart the print processor
CASBJ0037E job-number Spool purge failed: RC = return-code | Print processor failed. The return code was return-code. | Correct the problem and restart the print processor
CASBJ0038I job-number Spool SYSOUT Purged | Processing of job-number completed and the spool output has been purged | None
CASBJ0039E JES support not enabled; Start for Printer rejected | The requested Printer was not started because JES support is not enabled. | Enable support and retry the operation
CASBJ0040E JES support not enabled; Start for Initiator rejected | The requested Job Initiator was not started because JES support is not enabled. | Enable support and retry the operation
CASBJ0041E Printer JES interface initialization failed. RC=return-code The requested Printer output processor failed to start because JES initialization failed. Where, the possible return code are:
  • RC=20 - printer not found
  • RC=32 - an exception loading the printer exit - for example, printer exit module not found.
  • RC=100+ - printer exit return code. If the printer exit returns a non-zero return code, 100 will be added to this return code and this becomes the return code from the printer initialization.
Correct the error and retry the operation
CASBJ0042E Batch initiator JES interface initialization failed. RC=return-code | The requested initiator JES interface failed | Correct the error and retry the operation
CASBJ0043E JOB Submit JES interface initialization failed. RC=return-code | The requested JOB Submit JES interface failed | Correct the error and retry the operation
CASBJ0044I Batch initiator restart requested for job classes "job-classes" | A batch initiator is terminating because of a "dirty container" condition. It has requested that ES start a replacement for the classes "job-classes". | None
CASBJ0045I JOB%job-number, DD number dd-number, size dataset-size requested | [An external process requested this dataset and transmission has started | None
CASBJ0046S JES Submit: User ID "user-ID" invalid or password incorrect | A job submission request was submitted but the associated user ID was invalid or the supplied password was incorrect | Correct the credentials and retry the operation
CASBJ0047S JES Submit: User ID "user-ID" not authorized | A job submission request was submitted but the associated user ID is not authorized for this action | Retry the operation with authorized credentials
CASBJ0048S JES CASOUT: User ID "user-ID" invalid or password incorrect | An attempt was made to interact with a batch initiator, printer or retrieve spool information and the associated user ID was invalid or the supplied password was incorrect | Correct the credentials and retry the operation
CASBJ0049S JES CASOUT: User ID "user-ID" not authorized | An attempt was made to interact with a batch initiator, printer or retrieve spool information and the associated user ID is not authorized | Retry the operation with authorized credentials
CASBJ0050E JES support not enabled; Job rejected | The requested job was not submitted because JES support is not enabled. | Enable support and retry the operation
CASBJ0051E Batch initiator JES interface initialization failed for ES Cluster manager ES Cluster manager APPLID. RC=return-code | The requested initiator JES interface failed to connect to ES Cluster manager | Correct the error and retry the operation
CASBJ0052S Batch initiator JES interface initialization failed for ES Cluster manager ES Cluster manager APPLID. RC=return-code | Connection to the ES Cluster manager is lost, ES Cluster member cannot participate to the ES Cluster | Correct the error and retry the operation
Parent topic: Enterprise Server Error Messages


CASCD Error Messages

  • 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

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

  • 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.
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.
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
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.
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
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
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.
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.
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.
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.
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.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0016 - CASCD0031


CASCD0050 - CASCD0099

  • 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.
System Action:
None
Resolution:
None
Destination:
standard error
Module:
dfhrem
Parent topic: CASCD0050 - CASCD0099


CASCD0051F

The request to start a region was not successful
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
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
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.

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.
System Action:
None
Resolution:
None
Destination:
standard error
Module:
dfhserv
Parent topic: CASCD0050 - CASCD0099


CASCD0061F

The request to start a server was not successful
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
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
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.

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
System Action:
None
Resolution:
None
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0050 - CASCD0099


CASCD0100 - CASCD0117

  • 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
System Action:
None
Resolution:
None
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0100 - CASCD0117


CASCD0101I

The CAS Daemon has completed termination
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0100 - CASCD0117


CASCD0102F

The CAS Daemon has failed to initialize
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
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
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
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
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
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
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
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
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
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.

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

  • 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
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
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
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
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
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
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
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
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
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0130I

Region region-name has successfully completed termination
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
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
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
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
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
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
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.
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
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.
System Action:
Shutdown
Resolution:
None
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0141 - CASCD0159

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

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

  • 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 WebSphere MQ 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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0160 - CASCD0175


CASCD0171S

The WebSphere MQ gateway for region region-name has abended due to an unexpected signal signal-value.
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.
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
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.
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.
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

  • 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 WebSphere MQ Gateway has been started for region region-name This gateway emulates the CKTI trigger monitor transaction.
  • CASCD1033I
    The WebSphere MQ Gateway service process for region region-name has successfully completed termination
  • CASCD1034S
    The WebSphere MQ 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.
  • CASCD1042I
    The IMS TM Control Process has been started for Server server-name
  • CASCD1043I
    The IMS DB Control Process has been started for Server server-name
  • 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.
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.
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.
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.
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.
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.
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
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
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1032I

A WebSphere MQ Gateway has been started for region region-name This gateway emulates the CKTI trigger monitor transaction.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1033I

The WebSphere MQ Gateway service process for region region-name has successfully completed termination
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1034S

The WebSphere MQ Gateway process of region region-name has exited, the value specified on the exit call was exit-value
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
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
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
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
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
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
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.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1042I

The IMS TM Control Process has been started for Server server-name
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1043I

The IMS DB Control Process has been started for Server server-name
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
System Action:
None
Resolution:
None
Destination:
system console
Parent topic: CASCD1001 - CASCD1056


CASCD1057 - CASCD1069

  • CASCD1057S
    A JES Initiator for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1058S
    A JES Printer for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1059I
    An IMS MPR Process has been started for Server server-name
  • CASCD1060I
    An JES Initiator Process has been started for Server server-name
  • 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


CASCD1057S

A JES Initiator for Server server-name has abended due to an unexpected signal signal-value.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1057 - CASCD1069


CASCD1058S

A JES Printer for Server server-name has abended due to an unexpected signal signal-value.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1057 - CASCD1069


CASCD1059I

An IMS MPR Process has been started for Server server-name
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1057 - CASCD1069


CASCD1060I

An JES Initiator Process has been started for Server server-name
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1057 - CASCD1069


CASCD1061S

An undefined process request was received for Server server-name
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
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
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
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
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.
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
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
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
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1057 - CASCD1069


CASCD1070 - CASCD1200

  • 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.
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
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
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
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.
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
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
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
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.
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
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
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
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.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1083I

Enterprise Server Debug SEP created successfully.
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
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
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.
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.
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.
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.
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.
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.
System Action:
A SPOOLCLOSE command is assumed
Resolution:
A SPOOLCLOSE command is assumed
Destination:
console
Module:
dfhesysp
Parent topic: CASCD1070 - CASCD1200


CASCD4002 - CASCD4007

  • 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.
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.
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.
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.
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.
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.
System Action:
SYSACTION
Resolution:
Report the error to technical support
Destination:
console and standard error
Module:
dfhmd
Parent topic: CASCD4002 - CASCD4007


CASCF Error Messages

  • CASCF0001 - CASCF0015
  • CASCF0016 - CASCF0030
  • CASCF0031 - CASCF0045
  • CASCF0046 - CASCF0064
Parent topic: Enterprise Server Error Messages


CASCF0001 - CASCF0015

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

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

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

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

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

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

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.

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

On UNIX systems, this error can occur if the User ID used to start the region does not have the permissions to update existing files in the Enterprise Server workarea. The default WORKAREA directory path is /opt/mfcobol/es/<region name>

System Action:
Terminate the requesting process.
Resolution:
Make sure that the console daemon is active and retry. On UNIX systems, delete or rename the region workarea.
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.
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.
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.
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.
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.
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.
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.
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
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
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
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.
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

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


CASCL0005S 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.
 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 .
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.
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.
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.
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.
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.
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


CASCS Error Messages

  • CASCS1001 - CASCS1018
  • CASCS1100 - CASCS1115
  • CASCS1116 - CASCS1138
  • CASCS1500 - CASCS2004
  • CASCS3001 - CASCS5009
  • CASCS5010 - CASCS5104
Parent topic: Enterprise Server Error Messages


CASCS1001 - CASCS1018

  • CASCS1001S
    Inbound allocate for transaction trans-id failed because it could not acquire sufficient process storage to issue the receive allocate.
  • CASCS1002E
    Inbound allocate for transaction trans-id failed because of a communications error. trans-id is the primary return code of the communications layer.
  • CASCS1003S
    Inbound transaction routing of transaction trans-id failed because the terminal term-id is not owned by the remote system system-id. The request originated from a terminal that has the same term-id as another remote system or the term-id is defined as local to this CICS region.
  • CASCS1004S
    Inbound allocate for transaction trans-id failed because it could not acquire sufficient process storage to store the transmitted data.
  • CASCS1006E
    Inbound transaction trans-id from system system-id failed with a primary communications return code of comms-primary-RC.
  • CASCS1007E
    The terminal definition for terminal-id was requested from the remote system while trying to process transaction trans-id. The primary communications return code is comms-primary-RC.
  • CASCS1008E
    The install for terminal definition for terminal-id was rejected. The table manager return code is return-code.
  • CASCS1009S
    The install for terminal definition failed to acquire local storage during execution of transaction trans-id.
  • CASCS1010E
    A terminal definition was requested from system system-id. The response received was not a valid builder list.
  • CASCS1011E
    Outbound transaction routing of transaction trans-id to system system-id is not supported because there is no communications buffer allocated.
  • CASCS1012E
    Outbound transaction routing of transaction trans-id to system system-id failed with a communications return-code of comms-primary-RC. Refer to the communications protocol stack documentation for other return codes and for more information. Also note that some protocol stacks use different values for the above conditions.
  • CASCS1013E
    Outbound transaction routing of transaction trans-id failed because system system-id is not defined.
  • CASCS1014E
    Outbound transaction routing of transaction trans-id failed because system system-id is marked out of service.
  • CASCS1015E
    Outbound transaction routing of transaction trans-id failed because system system-id is not acquired.
  • CASCS1016E
    Outbound transaction routing of transaction trans-id failed because system system-id is not defined as a connection.
  • CASCS1017E
    Inbound transaction trans-id from system system-id failed security check for user user-id. The password supplied by the remote system was not valid.
  • CASCS1018E
    Inbound transaction trans-id from system system-id failed security check for user user-id. The user ID was not found in this system's SNT.
Parent topic: CASCS Error Messages


CASCS1001S

Inbound allocate for transaction trans-id failed because it could not acquire sufficient process storage to issue the receive allocate.
System Action:
The receive allocate is not issued and will time out based external communications parameters
Resolution:
This server will likely continue to fail. It should be terminated and restarted.
Destination:
TDQ CSMT
Module:
dfhebms (issued in dfheserv)
Parent topic: CASCS1001 - CASCS1018


CASCS1002E

Inbound allocate for transaction trans-id failed because of a communications error. trans-id is the primary return code of the communications layer.
System Action:
The receive allocate is not issued and will time out based external communications parameters
Resolution:
The most likely cause of this error is a definition error for the invocable transaction program
Destination:
TDQ CSMT
Module:
dfhebms (issued in dfheserv)
Parent topic: CASCS1001 - CASCS1018


CASCS1003S

Inbound transaction routing of transaction trans-id failed because the terminal term-id is not owned by the remote system system-id. The request originated from a terminal that has the same term-id as another remote system or the term-id is defined as local to this CICS region.
System Action:
The transaction is abended
Resolution:
Correct the terminal definitions
Destination:
TDQ CSMT
Module:
dfhebms (issued in dfheserv)
Parent topic: CASCS1001 - CASCS1018


CASCS1004S

Inbound allocate for transaction trans-id failed because it could not acquire sufficient process storage to store the transmitted data.
System Action:
The transaction is abnormally terminated
Resolution:
This server will likely continue to fail. It should be terminated and restarted.
Destination:
TDQ CSMT
Module:
dfhebms (issued in dfheserv)
Parent topic: CASCS1001 - CASCS1018


CASCS1006E

Inbound transaction trans-id from system system-id failed with a primary communications return code of comms-primary-RC.
System Action:
The transaction is abnormally terminated
Resolution:
Correct the communications problem indicated by comms-primary-RC
Destination:
TDQ CSMT
Module:
dfhebms (issued in dfheserv)
Parent topic: CASCS1001 - CASCS1018


CASCS1007E

The terminal definition for terminal-id was requested from the remote system while trying to process transaction trans-id. The primary communications return code is comms-primary-RC.
System Action:
The transaction is abnormally terminated
Resolution:
Correct the cause of the communications error
Destination:
TDQ CSMT
Module:
dfhebms (issued in dfheserv)
Parent topic: CASCS1001 - CASCS1018


CASCS1008E

The install for terminal definition for terminal-id was rejected. The table manager return code is return-code.
System Action:
The transaction is abnormally terminated
Resolution:
Correct the cause of the table conflict as indicated by the table manager return code return-code
Destination:
TDQ CSMT
Module:
dfhebms (issued in dfheserv)
Parent topic: CASCS1001 - CASCS1018


CASCS1009S

The install for terminal definition failed to acquire local storage during execution of transaction trans-id.
System Action:
The transaction is abnormally terminated
Resolution:
This server will likely continue to fail. It should be terminated and restarted.
Destination:
TDQ CSMT
Module:
dfhebms (issued in dfheserv)
Parent topic: CASCS1001 - CASCS1018


CASCS1010E

A terminal definition was requested from system system-id. The response received was not a valid builder list.
System Action:
The transaction is abnormally terminated
Resolution:
Verify the definition for the connection to the system-id system
Destination:
TDQ CSMT
Module:
dfhebms (issued in dfheserv)
Parent topic: CASCS1001 - CASCS1018


CASCS1011E

Outbound transaction routing of transaction trans-id to system system-id is not supported because there is no communications buffer allocated.
System Action:
The request is rejected
Resolution:
Check for errors during server startup
Destination:
user terminal and TDQ CSMT
Module:
dfhebms (issued in dfheserv)
Parent topic: CASCS1001 - CASCS1018


CASCS1012E

Outbound transaction routing of transaction trans-id to system system-id failed with a communications return-code of comms-primary-RC. Refer to the communications protocol stack documentation for other return codes and for more information. Also note that some protocol stacks use different values for the above conditions.

Common values for comms-primary-RC are:

  • x'0003' Allocation error (SYSIDERR)
  • x'000f' Conversation failure - retry
  • x'0010' Conversation failure - no retry
System Action:
The transaction is abnormally terminated
Resolution:
Correct the communications error and retry the operation
Destination:
user terminal and TDQ CSMT
Module:
dfhebms (issued in dfheserv)
Parent topic: CASCS1001 - CASCS1018


CASCS1013E

Outbound transaction routing of transaction trans-id failed because system system-id is not defined.
System Action:
The request is rejected
Resolution:
Add the resource definition for SYSID system-id
Destination:
user terminal and TDQ CSMT
Module:
dfhebms (issued in dfheserv)
Parent topic: CASCS1001 - CASCS1018


CASCS1014E

Outbound transaction routing of transaction trans-id failed because system system-id is marked out of service.
System Action:
The request is rejected
Resolution:
>Place the connection system-id in service and acquired
Destination:
user terminal and TDQ CSMT
Module:
dfhebms (issued in dfheserv)
Parent topic: CASCS1001 - CASCS1018


CASCS1015E

Outbound transaction routing of transaction trans-id failed because system system-id is not acquired.
System Action:
The request is rejected
Resolution:
Place the connection system-id in service and acquired
Destination:
user terminal and TDQ CSMT
Module:
dfhebms (issued in dfheserv)
Parent topic: CASCS1001 - CASCS1018


CASCS1016E

Outbound transaction routing of transaction trans-id failed because system system-id is not defined as a connection.
System Action:
The request is rejected
Resolution:
Correct the resource definition for SYSID system-id or point transaction to the correct SYSID
Destination:
user terminal and TDQ CSMT
Module:
dfhebms (issued in dfheserv)
Parent topic: CASCS1001 - CASCS1018


CASCS1017E

Inbound transaction trans-id from system system-id failed security check for user user-id. The password supplied by the remote system was not valid.
System Action:
The transaction is abnormally terminated
Resolution:
Correct the user password on either the local or remote system
Destination:
TDQ CSMT
Module:
dfhebms (issued in dfhecics)
Parent topic: CASCS1001 - CASCS1018


CASCS1018E

Inbound transaction trans-id from system system-id failed security check for user user-id. The user ID was not found in this system's SNT.
System Action:
The transaction is abnormally terminated
Resolution:
Correct the user ID on the remote system or add it locally
Destination:
TDQ CSMT
Module:
dfhebms (issued in dfhecics)
Parent topic: CASCS1001 - CASCS1018


CASCS1100 - CASCS1115

  • CASCS1100W
    An error occurred in the CCI communications of the CAS CCI gateway.
  • CASCS1101W
    An error occurred in the CCI communications of the CAS CCI gateway. CCI-error-text is returned from CCI. This message will be generated prior to message CASCS1100W for CCI error return code 9.
  • CASCS1102E
    An error occurred in registering system net-name. This is an internal error indicating a logic error or a module mismatch problem.
  • CASCS1103E
    An error occurred allocating local process storage. The process has exceeded the available address space. There are too many clients or traffic buffering is backed up in the gateway process.
  • CASCS1104I
    The CAS CCI gateway initialized successfully on specified port, remoterequesters can now connect to the region. The CCI network protocol supported is CCI-protocol.
  • CASCS1105S
    The CAS CCI gateway failed to initialize successfully . The reason-code is generally from the CCI protocol module. reason-code of 998 says the CCI protocol module could not be loaded. reason-code of 999 says the CCI protocol module signature was bad.
  • CASCS1106S
    The CAS CCI gateway failed to initialize successfully . The reason-code is from dfhgreqc.
  • CASCS1107W
    The CAS CCI gateway failed to connect to remote-region. The reason-codeis the CCI protocol return code.
  • CASCS1108I
    The CAS CCI gateway serving the CCI-protocol is shutting down.
  • CASCS1109I
    The CAS CCI gateway successfully connected to remote-region. It is accessible via sysid sys-id. This system is the contention winner or the client side of the connection.
  • CASCS1110I
    The CAS CCI gateway successfully connected to remote-region. It is accessible via sysid sys-id. This system is the contention loser or the server side of the connection.
  • CASCS1111E
    The CAS CCI gateway failed to connect to region remote-region.
  • CASCS1112E
    The CAS CCI gateway failed to connect to region remote-region.
  • CASCS1113S
    The CAS CCI gateway detected a CCI protocol error.
  • CASCS1114E
    An error occurred loading the protocol support module module-name.
  • CASCS1115E
    The signature check for CCI protocol support module module-namefailed. The signature found is CCI-signature-string.
Parent topic: CASCS Error Messages


CASCS1100W

An error occurred in the CCI communications of the CAS CCI gateway.

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

All error codes are from CCI. Numbers greater than 99 are specific to a net layer and do not map directly to one of the codes above. For NetBios, 100 is added to the net layer code to differentiate from the codes above. For further information check CCI return code documentation.

System Action:
None
Resolution:
None
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1101W

An error occurred in the CCI communications of the CAS CCI gateway. CCI-error-text is returned from CCI. This message will be generated prior to message CASCS1100W for CCI error return code 9.
System Action:
None
Resolution:
None
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1102E

An error occurred in registering system net-name. This is an internal error indicating a logic error or a module mismatch problem.
System Action:
The system is not registered
Resolution:
Report the problem to Micro Focus
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1103E

An error occurred allocating local process storage. The process has exceeded the available address space. There are too many clients or traffic buffering is backed up in the gateway process.
System Action:
The requested registration is rejected
Resolution:
Reduce the gateway loading
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1104I

The CAS CCI gateway initialized successfully on specified port, remoterequesters can now connect to the region. The CCI network protocol supported is CCI-protocol.
System Action:
None
Resolution:
None
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1105S

The CAS CCI gateway failed to initialize successfully . The reason-code is generally from the CCI protocol module. reason-code of 998 says the CCI protocol module could not be loaded. reason-code of 999 says the CCI protocol module signature was bad.
System Action:
Process terminates
Resolution:
Check that the CCITCP2 process is running on the machine specified in the SIT. Check that the specified CCI protocol stack is available. Check that the RTS is built properly. For TN3270, check that the specified or default port is available and that the CAS process has the permissions required to access it.
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1106S

The CAS CCI gateway failed to initialize successfully . The reason-code is from dfhgreqc.
System Action:
Process terminates
Resolution:
Check that the associated region is active
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1107W

The CAS CCI gateway failed to connect to remote-region. The reason-codeis the CCI protocol return code.
System Action:
The connection is marked as inactive
Resolution:
Check that the remote-region is active and that the system has a network path to remote-region for the protocol specified
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1108I

The CAS CCI gateway serving the CCI-protocol is shutting down.
System Action:
None
Resolution:
None
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1109I

The CAS CCI gateway successfully connected to remote-region. It is accessible via sysid sys-id. This system is the contention winner or the client side of the connection.
System Action:
The connection is available for work
Resolution:
None
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1110I

The CAS CCI gateway successfully connected to remote-region. It is accessible via sysid sys-id. This system is the contention loser or the server side of the connection.
System Action:
The connection is available for work
Resolution:
None
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1111E

The CAS CCI gateway failed to connect to region remote-region.

The reason is reason-code. Reason codes are:

  • 1 Name conflict (the netname references a non-system node)
  • 2 Locate error
  • 3 Auto-install error (The automatic connection install failed)
System Action:
The bind is rejected
Resolution:
None
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1112E

The CAS CCI gateway failed to connect to region remote-region.

The reason is reason-code. Reason codes are:

  • 1 Name conflict (the netname references a non-system node)
  • 2 Locate error
  • 3 Auto-install error (The automatic connection install failed)
  • 4 Contention reject (The bind is in progress from the remote system)
System Action:
The bind was rejected by the partner system
Resolution:
None
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1113S

The CAS CCI gateway detected a CCI protocol error.
System Action:
The CAS CCI gateway is terminated
Resolution:
Start the net requester service on the workstation
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1114E

An error occurred loading the protocol support module module-name.
System Action:
The CCI gateway will not initialize successfully
Resolution:
Correct the CCI installation or activate the underlying OS support such that the CCI module can be loaded
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1115E

The signature check for CCI protocol support module module-namefailed. The signature found is CCI-signature-string.
System Action:
The CCI gateway will not initialize successfully
Resolution:
Correct the CCI installation
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1100 - CASCS1115


CASCS1116 - CASCS1138

  • CASCS1116I
    The signature check string for CCI protocol support module module-nameis CCI-signature-string. This is a documentation message.
  • CASCS1117I
    The CAS CCI gateway connection to remote-region is lost. Active work on sysid sys-id will terminate abnormally. The CCI network protocol in use is CCI-transport.
  • CASCS1118W
    The CAS CCI gateway connection to remote-region is lost due to an abnormal termination on sysid sys-id. The CCI network protocol in use was CCI-transport.
  • CASCS1119I
    The CAS CCI gateway received an bind from region remote-region. The bind is rejected because the local region has initiated a bind to this remote region and contention rules dictate that the local region should be the contention winner.
  • CASCS1120W
    The communications server failed to establish an ISC connection to peer system remote-region. The CCI protocol return code is reason-code.
  • CASCS1121I
    The CAS CCI gateway successfully connected to the IBM Universal Client identified by netname remote-region. It is accessible via sysid sys-id. This system is the contention winner or the client side of the connection.
  • CASCS1122I
    The system is attempting to activate the connection (TCT) identified as sys-id to the region named remote-region.
  • CASCS1123I
    The client has made a connction request either from a machine with which a connection already exists or presenting a netname which is already in use.
  • CASCS1124I
    The CAS CCI gateway connection to remote-region is releasing. The action is at the request of the remote system. Active work on sysid sys-id will terminate abnormally. The CCI network protocol in use is CCI-transport.
  • CASCS1125I
    The CAS CCI gateway connection to remote-region is releasing. The action is at the request of the local system. Active work on sysid sys-id will terminate abnormally. The CCI network protocol in use is CCI-transport.
  • CASCS1126I ES Cluster manager successfully negotiated with ES Cluster client APPLID of node.
    The ES Cluster manager has successfully negotiated with a ES cluster client.
  • CASCS1131S
    An error occurred whilst processing the region configuration file.
  • CASCS1132S
    An error occurred while processing the configuration file.
  • CASCS1133S
    An unrecognized line was found in the configuration file at the line shown.
  • CASCS1134S
    The configuration file could not be found.
  • CASCS1135S
    An error occurred when creating the configuration save file.
  • CASCS1136S
    An error occurred when creating the configuration save file.
  • CASCS1137S
    An error occurred when reading the configuration save file.
  • CASCS1138S
    An error occurred when writing the configuration save file.
Parent topic: CASCS Error Messages


CASCS1116I

The signature check string for CCI protocol support module module-nameis CCI-signature-string. This is a documentation message.
System Action:
The CCI gateway will continue initialization
Resolution:
None
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1116 - CASCS1138


CASCS1117I

The CAS CCI gateway connection to remote-region is lost. Active work on sysid sys-id will terminate abnormally. The CCI network protocol in use is CCI-transport.
System Action:
The connection sys-id is no longer available for work
Resolution:
Restart peer region
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1116 - CASCS1138


CASCS1118W

The CAS CCI gateway connection to remote-region is lost due to an abnormal termination on sysid sys-id. The CCI network protocol in use was CCI-transport.
System Action:
The connection sys-id is no longer available for work
Resolution:
None
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1116 - CASCS1138


CASCS1119I

The CAS CCI gateway received an bind from region remote-region. The bind is rejected because the local region has initiated a bind to this remote region and contention rules dictate that the local region should be the contention winner.
System Action:
The bind from the remote region is rejected. The bind initiated by the local region is allowed to continue
Resolution:
None
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1116 - CASCS1138


CASCS1120W

The communications server failed to establish an ISC connection to peer system remote-region. The CCI protocol return code is reason-code.
System Action:
The bind for the peer server is silently retried until the ISC connection status changes
Resolution:
Check that the remote-region is active and that the system has a network path to remote-region for the protocol specified
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1116 - CASCS1138


CASCS1121I

The CAS CCI gateway successfully connected to the IBM Universal Client identified by netname remote-region. It is accessible via sysid sys-id. This system is the contention winner or the client side of the connection.
System action:
The connection is available for work.
Resolution:
None
Destination:
Console
Module:
dfhtcci
Parent topic: CASCS1116 - CASCS1138


CASCS1122I

The system is attempting to activate the connection (TCT) identified as sys-id to the region named remote-region.
System action:
Resolution:
Destination:
Console
Module:
dfhtcci
Parent topic: CASCS1116 - CASCS1138


CASCS1123I

The client has made a connction request either from a machine with which a connection already exists or presenting a netname which is already in use.
System action:
Resolution:
Destination:
Console
Module:
casgate
Parent topic: CASCS1116 - CASCS1138


CASCS1124I

The CAS CCI gateway connection to remote-region is releasing. The action is at the request of the remote system. Active work on sysid sys-id will terminate abnormally. The CCI network protocol in use is CCI-transport.
System action:
The connection sys-id will no longer be available for work.
Resolution:
No user action is required.
Destination:
Console
Module:
casgate
Parent topic: CASCS1116 - CASCS1138


CASCS1125I

The CAS CCI gateway connection to remote-region is releasing. The action is at the request of the local system. Active work on sysid sys-id will terminate abnormally. The CCI network protocol in use is CCI-transport.
System action:
The connection sys-id will no longer be available for work.
Resolution:
No user action is required.
Destination:
Console
Module:
casgate
Parent topic: CASCS1116 - CASCS1138


CASCS1126I ES Cluster manager successfully negotiated with ES Cluster client APPLID of node.

The ES Cluster manager has successfully negotiated with a ES cluster client.
System Action:
Master now knows about another Es cluster client.
Resolution:
None.
Module:
casgate
Destination:
System Console.
Parent topic: CASCS1116 - CASCS1138


CASCS1131S

An error occurred whilst processing the region configuration file.
System action:
The CCI gateway will not initialize successfully.
Resolution:
Correct the fault with the configuration file.
Destination:
Console
Module:
dfhtcci
Parent topic: CASCS1116 - CASCS1138


CASCS1132S

An error occurred while processing the configuration file.
System action:
The CCI gateway will not initialize successfully.
Resolution:
Correct the fault with the configuration file.
Destination:
Console
Module:
dfhtcci
Parent topic: CASCS1116 - CASCS1138


CASCS1133S

An unrecognized line was found in the configuration file at the line shown.
System Action:
The CCI gateway will not initialize successfully
Resolution:
Correct the fault with the configuration file ensuring that the line contains a valid configuration item
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1116 - CASCS1138


CASCS1134S

The configuration file could not be found.
System Action:
The CCI gateway will not initialize successfully
Resolution:
Make sure that CASDIR is set correctly and that the configuration file exists
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1116 - CASCS1138


CASCS1135S

An error occurred when creating the configuration save file.
System Action:
The CCI gateway will not initialize successfully
Resolution:
Check directory permissions and disk space
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1116 - CASCS1138


CASCS1136S

An error occurred when creating the configuration save file.
System Action:
The CCI gateway will not initialize successfully
Resolution:
Check directory permissions and disk space
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1116 - CASCS1138


CASCS1137S

An error occurred when reading the configuration save file.
System Action:
The CCI gateway will not initialize successfully
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1116 - CASCS1138


CASCS1138S

An error occurred when writing the configuration save file.
System Action:
The CCI gateway will not initialize successfully
Resolution:
Check directory permissions and disk space
Destination:
console
Module:
dfhtcci
Parent topic: CASCS1116 - CASCS1138


CASCS1500 - CASCS2004

  • CASCS1500I
    The CAS gateway initialized successfully. Remote requesters can now connect to the region.
  • CASCS1501I
    The CAS gateway has started shutdown processing.
  • CASCS1502W
    The CAS gateway failed to initialize successfully.
  • CASCS2001E
    A systems data stream was received by the CAS mirror transaction trans-ID that is logically too short to decode.
  • CASCS2002E
    A systems data stream was received by the CAS mirror transaction trans-ID that is not supported. It is not an FMH 5, 6, or 43.
  • CASCS2003E
    A systems data stream was received by the CAS mirror transaction trans-ID that contained an invalid structured field.
  • CASCS2004E
    The systems transaction trans-ID was executed from an invalid terminal type. term-ID is the originating terminal. The most most likely cause of this error is that a user entered this transaction in error.
Parent topic: CASCS Error Messages


CASCS1500I

The CAS gateway initialized successfully. Remote requesters can now connect to the region.
System Action:
None
Resolution:
None
Destination:
console
Module:
hydra
Parent topic: CASCS1500 - CASCS2004


CASCS1501I

The CAS gateway has started shutdown processing.
System Action:
None
Resolution:
None
Destination:
console
Module:
hydra
Parent topic: CASCS1500 - CASCS2004


CASCS1502W

The CAS gateway failed to initialize successfully.
System Action:
None
Resolution:
None
Destination:
console
Module:
hydra
Parent topic: CASCS1500 - CASCS2004


CASCS2001E

A systems data stream was received by the CAS mirror transaction trans-ID that is logically too short to decode.
System Action:
The transaction is abended and the conversation is terminated
Resolution:
If the problem persists, determine the reason that the partner system is generating the short request data streams and correct the problem
Destination:
TDQ CSMT
Module:
dfhzcsmi
Parent topic: CASCS1500 - CASCS2004


CASCS2002E

A systems data stream was received by the CAS mirror transaction trans-ID that is not supported. It is not an FMH 5, 6, or 43.
System Action:
The transaction is abended and the conversation is terminated
Resolution:
If the problem persists, determine the reason that the partner system is generating the unsupported FMH data and correct the problem
Destination:
TDQ CSMT
Module:
dfhzcsmi
Parent topic: CASCS1500 - CASCS2004


CASCS2003E

A systems data stream was received by the CAS mirror transaction trans-ID that contained an invalid structured field.
System Action:
The transaction is abended and the conversation is terminated
Resolution:
If the problem persists, determine the reason that the partner system is generating the invalid structured field and correct the problem
Destination:
TDQ CSMT
Module:
dfhzcsmi
Parent topic: CASCS1500 - CASCS2004


CASCS2004E

The systems transaction trans-ID was executed from an invalid terminal type. term-ID is the originating terminal. The most most likely cause of this error is that a user entered this transaction in error.
System Action:
The transaction and conversation is terminated
Resolution:
None
Destination:
User terminal and TDQ CSMT
Module:
dfhzcrsr
Parent topic: CASCS1500 - CASCS2004


CASCS3001 - CASCS5009

  • CASCS3001
    An inbound allocate was received from region-name for region partner-lu-alias was rejected because the designate target region was either not valid or not active. The transaction specified is transaction-id.
  • CASCS3002
    An inbound allocate was received from region-name for region partner-lu-alias. The receive allocate failed with a primary return code of return-code. The transaction specified is transaction-id. A previous error also occurred. Either the parameters passed to dfhgatch were bad or the region specified was invalid or inactive.
  • CASCS3031
    An inbound allocate was received from netname and was automatically installed with default connection parameters.
  • CASCS3032S Connection to ES Cluster manager remote-region (sysid sys-id) is disabled, verify and release global locks on ES cluster manager
    The CAS gateway connection to remote-region is lost after GLM timeout exceeded.
  • CASCS3033S Attempt to connect to a disabled ES Cluster manager remote-region (sysid sys-id), verify and release global locks on ES cluster manager
    The CAS gateway connection to remote-region has been disabled.
  • CASCS3034S connection to remote-region (sysid sys-id) has timed out, verify connection and release any outstanding lock if required
    The CAS gateway connection to remote-region is lost after GLM timeout exceeded.
  • CASCS3035E ISC listener start request failed with RC MFCS return code received for the start listener request
    The ISC listener could not be started.
  • CASCS3036E GLM MFCS return code received for the start listener request (sysid ) is in "NOWORK" state, waiting for all ES Cluster clients to send their locks. Check message KC6008S on the GLM.
    The ISC listener could not be started.
  • CASCS4001
    The transaction completed normally.
  • CASCS5001
    The region communications interface initialization process has started.
  • CASCS5002
    The region interface initialization process does not have the required underlying thread support.
  • CASCS5003
    The region interface initialization process has completed.
  • CASCS5004
    The region interface initialization process failed regestering the master session. The reason code is reason-code.
  • CASCS5005
    The communications interface experienced a problem allocating control blocks in local storage.
  • CASCS5006
    The region interface initialization process issued a message. The text is casgate-message.
  • CASCS5007
    The region communications interface is terminating.
  • CASCS5008
    The region communications interface has terminated.
  • CASCS5009
    Client registration failed for a new client session. The reason code is reason-code. The values and their meanings are as follows: 12: The system is in shutdown mode, and a new client is attempting to connect. This may happen if a server is suspended during shutdown.
Parent topic: CASCS Error Messages


CASCS3001

An inbound allocate was received from region-name for region partner-lu-alias was rejected because the designate target region was either not valid or not active. The transaction specified is transaction-id.
System Action:
The conversation is deallocated with an abend.
Resolution:
Start the region or correct the specification for the started transaction program.
Module:
dfhgatch
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS3002

An inbound allocate was received from region-name for region partner-lu-alias. The receive allocate failed with a primary return code of return-code. The transaction specified is transaction-id. A previous error also occurred. Either the parameters passed to dfhgatch were bad or the region specified was invalid or inactive.
System Action:
The initiating attach is left unanswered and will fail according to the specifications in the LU6.2 communications package.
Resolution:
Correct the parameters to dfhgatch or start the target region.
Module:
dfhgatch
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS3031

An inbound allocate was received from netname and was automatically installed with default connection parameters.
System Action:
Continue processing.
Module:
dfheappc
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS3032S Connection to ES Cluster manager remote-region (sysid sys-id) is disabled, verify and release global locks on ES cluster manager

The CAS gateway connection to remote-region is lost after GLM timeout exceeded.
System Action:
Identify why connection was lost, release ES Cluster clients locks on ES Cluster manager if client ES cluster connection loss only.
Resolution:
No user action is required.
Module:
casgate
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS3033S Attempt to connect to a disabled ES Cluster manager remote-region (sysid sys-id), verify and release global locks on ES cluster manager

The CAS gateway connection to remote-region has been disabled.
System Action:
No sys action is required.
Resolution:
No user action is required.
Module:
casgate
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS3034S connection to remote-region (sysid sys-id) has timed out, verify connection and release any outstanding lock if required

The CAS gateway connection to remote-region is lost after GLM timeout exceeded.
System Action:
Identify why connection to the cluster client is lost, release ES Cluster clients locks on ES Cluster manager if required.
Resolution:
No user action is required.
Module:
casgate
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS3035E ISC listener start request failed with RC MFCS return code received for the start listener request

The ISC listener could not be started.
System Action:
Identify if the requested port is in use for the listener.
Resolution:
No user action is required.
Module:
casgate
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS3036E GLM MFCS return code received for the start listener request (sysid ) is in "NOWORK" state, waiting for all ES Cluster clients to send their locks. Check message KC6008S on the GLM.

The ISC listener could not be started.
System Action:
Identify if the requested port is in use for the listener.
Resolution:
No user action is required.
Module:
casgate
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS4001

The transaction completed normally.
Module:
dfhzcgwy
Destination:
Terminal
Parent topic: CASCS3001 - CASCS5009


CASCS5001

The region communications interface initialization process has started.
Module:
casgate
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS5002

The region interface initialization process does not have the required underlying thread support.
System Action:
The communications facility is terminated.
Resolution:
Report failure to Micro Focus.
Module:
casgate
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS5003

The region interface initialization process has completed.
Module:
casgate
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS5004

The region interface initialization process failed regestering the master session. The reason code is reason-code.
System Action:
The communications facility is terminated.
Resolution:
Report failure to Micro Focus.
Module:
casgate
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS5005

The communications interface experienced a problem allocating control blocks in local storage.
System Action:
Interface is terminated.
Resolution:
Notify Micro Focus Support.
Module:
casgate
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS5006

The region interface initialization process issued a message. The text is casgate-message.
System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
casgate
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS5007

The region communications interface is terminating.
Module:
casgate
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS5008

The region communications interface has terminated.
Module:
casgate
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS5009

Client registration failed for a new client session. The reason code is reason-code. The values and their meanings are as follows: 12: The system is in shutdown mode, and a new client is attempting to connect. This may happen if a server is suspended during shutdown.
System Action:
Reject the client request.
Resolution:
None.
Module:
casgate
Destination:
Console
Parent topic: CASCS3001 - CASCS5009


CASCS5010 - CASCS5104

  • CASCS5010I
    The maximum number of sessions supported for Universal Client connections is 127. The value of the region configuration item CAS_UNICLI_SESSIONS exceeds this limit.
  • CASCS5011W
    MFCS failed to open the port for the TCPIPSERVICE TCPIPSERVICE name
  • CASCS5100I
    An informational message generated from a Communications Server.
  • CASCS5101W
    A warning message generated from a Communications Server.
  • CASCS5102E
    An error message generated from a Communications Server.
  • CASCS5103S
    A severe error message generated from a Communications Server.
  • CASCS5104S severe-error-msg
    A severe error message generated from a Communications Server.
Parent topic: CASCS Error Messages


CASCS5010I

The maximum number of sessions supported for Universal Client connections is 127. The value of the region configuration item CAS_UNICLI_SESSIONS exceeds this limit.
System action:
None
Resolution:
None
Destination:
Console
Module:
casgate
Parent topic: CASCS5010 - CASCS5104


CASCS5011W

MFCS failed to open the port for the TCPIPSERVICE TCPIPSERVICE name
System action:
TCPIPSERVICE TCPIPSERVICE name status set to Closed.
Resolution:
Check if port is already in use.
Destination:
Console
Module:
casgate
Parent topic: CASCS5010 - CASCS5104


CASCS5100I

An informational message generated from a Communications Server.
System action:
None.
Resolution:
None
Destination:
System Console
Module:
casgate
Parent topic: CASCS5010 - CASCS5104


CASCS5101W

A warning message generated from a Communications Server.
System action:
None.
Resolution:
None
Destination:
System Console
Module:
casgate
Parent topic: CASCS5010 - CASCS5104


CASCS5102E

An error message generated from a Communications Server.
System action:
None.
Resolution:
None
Destination:
System Console
Module:
casgate
Parent topic: CASCS5010 - CASCS5104


CASCS5103S

A severe error message generated from a Communications Server.
System action:
None.
Resolution:
None
Destination:
System Console
Module:
casgate
Parent topic: CASCS5010 - CASCS5104


CASCS5104S severe-error-msg

A severe error message generated from a Communications Server.
System Action:
None.
Module:
casgate
Destination:
System Console
Parent topic: CASCS5010 - CASCS5104


CASCT Error Messages

  • CASCS0000 - CASCT0095
  • CASCT0100 - CASCT0600
  • CASCT0700 - CASCT1000
  • CASCT2000 - CASCT3000
  • CASCT5000 - CASCT6110
Parent topic: Enterprise Server Error Messages


CASCS0000 - CASCT0095

  • CASCT0000S No messages found
    No errors or informational messages have been detected for this screen.
  • CASCT0001E Invalid key pressed
    You have pressed a key that is currently not defined for this screen.
  • CASCT0010E Codeset flag missing
    You must enter the codeset for the file you are trying to edit.
  • CASCT0015E Codeset entry invalid
    You have entered a value for the codeset other than 'A' or 'E' or ' ' or '_'.
  • CASCT0020E Selection missing
    You are missing the selection flag.
  • CASCT0030E Selection or codeset missing
    Either the codeset or the selection flag is missing.
  • CASCT0035E Highlighted field(s) have invalid hex characters
    Invalid hex characters have been entered.
  • CASCT0037E Missing quote in hex string
    The hex string that was entered is missing a quote character.
  • CASCT0038E Missing quote in character string
    The character string that was entered is missing a quote character.
  • CASCT0040E Highlighted field(s) in error, page up disabled
    Highlighted field(s) have an error, paging backwards not allowed until field(s) are fixed.
  • CASCT0045E Highlighted field(s) in error, page down disabled
    Highlighted field(s) have an error, paging forwards not allowed until field(s) are fixed.
  • CASCT0050E Highlighted field(s) in error, update disabled
    Highlighted field(s) have an error, update of fields not allowed until field(s) are fixed.
  • CASCT0070E Invalid selection, must be K, E, or R
    The highlighted field is in error, you must enter a valid value before transfer will take place.
  • CASCT0080E More than 1 FROM and TO selection
    You have selected more than 1 FROM and more than 1 TO. You can only copy from 1 file and place the results in 1 file.
  • CASCT0081E More than 1 FROM selection
    You have selected more than 1 FROM item. You can only copy from 1 file and place the results in 1 file.
  • CASCT0082E More than 1 TO selection
    You have selected more than 1 TO item. You can only copy to 1 file.
  • CASCT0085E Remote file FROM/TO entry
    You have selected a FROM/TO file that is marked as REMOTE. You must enter the file type.
  • CASCT0087E File type error
    You have entered a file type which is invalid or you are missing a file type entry.
  • CASCT0090E You cannot copy a file onto itself
    The FROM and TO file names are exactly the same. You must copy TO a different file.
  • CASCT0095W Copy option warnings, see line message(s)
    Copy options have warnings, see line messages for details.
Parent topic: CASCT Error Messages


CASCT0000S No messages found

No errors or informational messages have been detected for this screen.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCS0000 - CASCT0095


CASCT0001E Invalid key pressed

You have pressed a key that is currently not defined for this screen.
Resolution:
Select different key.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCS0000 - CASCT0095


CASCT0010E Codeset flag missing

You must enter the codeset for the file you are trying to edit.
Resolution:
Enter 'E' for EBCDIC or 'A' for ASCII or ' ' or '_' for UNKNOWN.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCS0000 - CASCT0095


CASCT0015E Codeset entry invalid

You have entered a value for the codeset other than 'A' or 'E' or ' ' or '_'.
Resolution:
Enter (E) for EBCDIC or (A) for ASCII or space for UNKNOWN.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCS0000 - CASCT0095


CASCT0020E Selection missing

You are missing the selection flag.
Resolution:
Enter 'S' on the line you want to edit.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCS0000 - CASCT0095


CASCT0030E Selection or codeset missing

Either the codeset or the selection flag is missing.
Resolution:
Enter the selection flag 'S' or codeset 'A'/'E/' '/'_'.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCS0000 - CASCT0095


CASCT0035E Highlighted field(s) have invalid hex characters

Invalid hex characters have been entered.
Resolution:
Enter valid hex characters. Spacing over invalid fields will reload previous value. Clear key will reload from last changed record.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCS0000 - CASCT0095


CASCT0037E Missing quote in hex string

The hex string that was entered is missing a quote character.
Resolution:
Enter the missing quote.
Module:
dfhzdfdm
Parent topic: CASCS0000 - CASCT0095


CASCT0038E Missing quote in character string

The character string that was entered is missing a quote character.
Resolution:
Enter the missing quote.
Module:
dfhzdfdm
Parent topic: CASCS0000 - CASCT0095


CASCT0040E Highlighted field(s) in error, page up disabled

Highlighted field(s) have an error, paging backwards not allowed until field(s) are fixed.
Resolution:
Fix field(s) in error.
Module:
dfhzdfdm
Parent topic: CASCS0000 - CASCT0095


CASCT0045E Highlighted field(s) in error, page down disabled

Highlighted field(s) have an error, paging forwards not allowed until field(s) are fixed.
Resolution:
Fix field(s) in error.
Module:
dfhzdfdm
Parent topic: CASCS0000 - CASCT0095


CASCT0050E Highlighted field(s) in error, update disabled

Highlighted field(s) have an error, update of fields not allowed until field(s) are fixed.
Resolution:
Fix field(s) in error.
Module:
dfhzdfdm
Parent topic: CASCS0000 - CASCT0095


CASCT0070E Invalid selection, must be K, E, or R

The highlighted field is in error, you must enter a valid value before transfer will take place.
Resolution:
Fix field in error: enter K, E or R.
Module:
dfhzdfdm
Parent topic: CASCS0000 - CASCT0095


CASCT0080E More than 1 FROM and TO selection

You have selected more than 1 FROM and more than 1 TO. You can only copy from 1 file and place the results in 1 file.
Resolution:
Remove duplicate 'F' and duplicate 'T'.
Module:
dfhzdfdm
Parent topic: CASCS0000 - CASCT0095


CASCT0081E More than 1 FROM selection

You have selected more than 1 FROM item. You can only copy from 1 file and place the results in 1 file.
Resolution:
Remove duplicate 'F'.
Module:
dfhzdfdm
Parent topic: CASCS0000 - CASCT0095


CASCT0082E More than 1 TO selection

You have selected more than 1 TO item. You can only copy to 1 file.
Resolution:
Remove duplicate 'T'.
Module:
dfhzdfdm
Parent topic: CASCS0000 - CASCT0095


CASCT0085E Remote file FROM/TO entry

You have selected a FROM/TO file that is marked as REMOTE. You must enter the file type.
Resolution:
Enter the file type.
Module:
dfhzdfdm
Parent topic: CASCS0000 - CASCT0095


CASCT0087E File type error

You have entered a file type which is invalid or you are missing a file type entry.
Resolution:
Enter a valid file type.
Module:
dfhzdfdm
Parent topic: CASCS0000 - CASCT0095


CASCT0090E You cannot copy a file onto itself

The FROM and TO file names are exactly the same. You must copy TO a different file.
System Action:
The copy was aborted.
Resolution:
Specify different files.
Module:
dfhzdfdm
Parent topic: CASCS0000 - CASCT0095


CASCT0095W Copy option warnings, see line message(s)

Copy options have warnings, see line messages for details.
Resolution:
Either fix warnings or press the copy key to ignore.
Module:
dfhzdfdm
Parent topic: CASCS0000 - CASCT0095


CASCT0100 - CASCT0600

  • CASCT0100E Record length error
    Requested record length is in error. You have probably entered a record length that is greater than the maximum record size.
  • CASCT0200E Record not found or file is empty
    Requested record is either not on file or the file is empty.
  • CASCT0203E FROM field blank
    The FROM field is blank, you must have a file name selected.
  • CASCT0205S Internal error
    There has been an internal logic error in the application. You may have tried to access an unsupported function.
  • CASCT0210E Init key valid only when adding a record
    You can only initialize a record when you are adding it.
  • CASCT0250E Illogic
    The request for a record is logically impossible. The file may not physically exist.
  • CASCT0300E File not found
    File you are trying to edit has not been created or is not on TRANPATH.
  • CASCT0305E Error creating sequential file
    The file name you entered cannot be created.
  • CASCT0310E File format invalid
    The format you have selected is either invalid or missing.
  • CASCT0325E SYSIDERR, EIBRESP = EIBRESP2 =
    The file you are trying to access has encountered a SYSIDERR. The comms link to the remote file has probably not been established.
  • CASCT0350E File IO error, EIBRESP = EIBRESP2 =
    The file you are trying to access has encountered a file I/O error. See EIBRESP for details.
  • CASCT0360E Cannot currently traverse DUPKEYs backwards
    The alternate index that you are reading has duplicate keys. Currently, the program cannot handle this situation when browsing backwards.
  • CASCT0400E Record already on file
    The record you are trying to add is already on file. The record has already been added or the key has not been changed before pressing the add key.
  • CASCT0500E Error occurred while rewriting record
    An error occurred while trying to update the record. The record may have been deleted before the record could be updated or an IO error occurred on the file.
  • CASCT0550E Error occurred while reading for update
    An error occurred while trying to update the record. The record may have been deleted before the record could be read for update or an IO error occurred on the file.
  • CASCT0555E Record modified since last read: update aborted
    The record has changed since last being read.
  • CASCT0600E Error occurred while reading TS queue
    An error occurred while trying to read a TS queue. The queue has been deleted or an IO error occurred.
Parent topic: CASCT Error Messages


CASCT0100E Record length error

Requested record length is in error. You have probably entered a record length that is greater than the maximum record size.
Resolution:
Re-input record length.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0200E Record not found or file is empty

Requested record is either not on file or the file is empty.
Resolution:
Use Add key to create a record.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0203E FROM field blank

The FROM field is blank, you must have a file name selected.
Resolution:
Make sure the FROM field contains a valid file name.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0205S Internal error

There has been an internal logic error in the application. You may have tried to access an unsupported function.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0210E Init key valid only when adding a record

You can only initialize a record when you are adding it.
Resolution:
Press the Add key if you want to add a record, then the Init key if you want to initialize it.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0250E Illogic

The request for a record is logically impossible. The file may not physically exist.
Resolution:
Make sure the file exists before editing it.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT0100 - CASCT0600


CASCT0300E File not found

File you are trying to edit has not been created or is not on TRANPATH.
Resolution:
Create the file using CFCR or create file using the Workbench fileloader. Check TRANPATH to see if file exists.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0305E Error creating sequential file

The file name you entered cannot be created.
Resolution:
Check the path and file name are valid.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0310E File format invalid

The format you have selected is either invalid or missing.
Resolution:
Enter 'F' for Fixed or 'V' for Variable.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0325E SYSIDERR, EIBRESP = EIBRESP2 =

The file you are trying to access has encountered a SYSIDERR. The comms link to the remote file has probably not been established.
Resolution:
Make sure function shipping is working correctly.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0350E File IO error, EIBRESP = EIBRESP2 =

The file you are trying to access has encountered a file I/O error. See EIBRESP for details.
Resolution:
Verify file is accessible.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0360E Cannot currently traverse DUPKEYs backwards

The alternate index that you are reading has duplicate keys. Currently, the program cannot handle this situation when browsing backwards.
Resolution:
Enter another key to reset the browse position.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0400E Record already on file

The record you are trying to add is already on file. The record has already been added or the key has not been changed before pressing the add key.
Resolution:
Change the key and add the record again.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0500E Error occurred while rewriting record

An error occurred while trying to update the record. The record may have been deleted before the record could be updated or an IO error occurred on the file.
Resolution:
Re-query the record to see if it still exists and try again.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0550E Error occurred while reading for update

An error occurred while trying to update the record. The record may have been deleted before the record could be read for update or an IO error occurred on the file.
Resolution:
Re-query the record to see if it still exists and try again.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0555E Record modified since last read: update aborted

The record has changed since last being read.
System Action:
The record was not updated.
Resolution:
Re-query the changed record and try again. Make a note of any changes you have made as they will be lost once the record is re-read.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0600E Error occurred while reading TS queue

An error occurred while trying to read a TS queue. The queue has been deleted or an IO error occurred.
Resolution:
Re-query the record to see if the problem still exists.
Module:
dfhzdfdm
Parent topic: CASCT0100 - CASCT0600


CASCT0700 - CASCT1000

  • CASCT0700E Error occurred while deleting record
    An error occurred while deleting a record. The record may have already been deleted or an IO error has occurred.
  • CASCT0710E FROM file name could not be located
    You have entered a file name which could not be found. This may be because the file does not exist or the path name is incorrect.
  • CASCT0715W File does not exist, will be created
    The file name you entered does not exist in the directory specified.
  • CASCT0720W File exists, TO file will be overlaid
    The file name you entered has been found, the overlay flag is on, therefore the TO file will be overlaid.
  • CASCT0725W File exists, TO file will be appended
    The file name you entered has been found, the overlay flag is off, therefore the TO file will be appended.
  • CASCT0750E Error occurred while adding record
    An error occurred while adding this record. The record may have already been added.
  • CASCT0800E Invalid line position
    You have pressed an INSERT/REMOVE line key but the cursor is not positioned in the text field.
  • CASCT1000W No files match selection criteria
    No file(s) found for the data entered in the file ID field. No file exists for the characters entered or the case is incorrect.
Parent topic: CASCT Error Messages


CASCT0700E Error occurred while deleting record

An error occurred while deleting a record. The record may have already been deleted or an IO error has occurred.
Resolution:
Re-query the record to see if the problem still exists.
Module:
dfhzdfdm
Parent topic: CASCT0700 - CASCT1000


CASCT0710E FROM file name could not be located

You have entered a file name which could not be found. This may be because the file does not exist or the path name is incorrect.
Resolution:
Make sure the path is correct and the CICS file name exists.
Module:
dfhzdfdm
Parent topic: CASCT0700 - CASCT1000


CASCT0715W File does not exist, will be created

The file name you entered does not exist in the directory specified.
System Action:
The file will be created.
Module:
dfhzdfdm
Parent topic: CASCT0700 - CASCT1000


CASCT0720W File exists, TO file will be overlaid

The file name you entered has been found, the overlay flag is on, therefore the TO file will be overlaid.
System Action:
The file will be overlaid.
Resolution:
Cancel if you don't want the file overlaid or turn the overlay flag off.
Module:
dfhzdfdm
Parent topic: CASCT0700 - CASCT1000


CASCT0725W File exists, TO file will be appended

The file name you entered has been found, the overlay flag is off, therefore the TO file will be appended.
System Action:
The file will be appended.
Resolution:
Cancel if you don't want the file appended or turn the overlay flag on.
Module:
dfhzdfdm
Parent topic: CASCT0700 - CASCT1000


CASCT0750E Error occurred while adding record

An error occurred while adding this record. The record may have already been added.
Resolution:
Change the key and try again.
Module:
dfhzdfdm
Parent topic: CASCT0700 - CASCT1000


CASCT0800E Invalid line position

You have pressed an INSERT/REMOVE line key but the cursor is not positioned in the text field.
Resolution:
Select different key.
Module:
dfhzdfdm
Parent topic: CASCT0700 - CASCT1000


CASCT1000W No files match selection criteria

No file(s) found for the data entered in the file ID field. No file exists for the characters entered or the case is incorrect.
Resolution:
Blank out the file ID using spaces and see what is listed. Be sure to check case.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT0700 - CASCT1000


CASCT2000 - CASCT3000

  • CASCT2000W Only one page available
    You have pressed a page forward or backwards key with no pages available.
  • CASCT2001W Wrapped
    You have wrapped around to either the first page or last page available.
  • CASCT2010I Press F9 key to edit
    You must press the edit key to enter into the editor.
  • CASCT2100I Record initialized
    The record has been initialized with the space character.
  • CASCT2110E Use CFLE or CFLS transactions to edit remote files
    You have tried to edit a remote file but you do not have the authority.
  • CASCT2200I Fill in data and press Add key
    Screen is in add mode, enter the desired information and press Add key again to add record.
  • CASCT2300I To copy record, press Add key
    To copy record, change the information and press the Add key again.
  • CASCT2310I To copy record, change key and press Add key
    To copy record, change the key information and press the Add key again.
  • CASCT2400I Top of file reached
    The beginning of the file has been reached, no more records available in this direction.
  • CASCT2425I Top of record reached
    The beginning of the record has been reached, no more pages available in this direction.
  • CASCT2450I Bottom of file reached
    The end of the file has been reached, no more records available in this direction.
  • CASCT2475I Bottom of record reached
    The end of the record has been reached, no more pages available in this direction.
  • CASCT3000I Search string not found
    The string entered in the search could not be found. Either the number of records or the number of bytes searched are displayed.
Parent topic: CASCT Error Messages


CASCT2000W Only one page available

You have pressed a page forward or backwards key with no pages available.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT2000 - CASCT3000


CASCT2001W Wrapped

You have wrapped around to either the first page or last page available.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT2000 - CASCT3000


CASCT2010I Press F9 key to edit

You must press the edit key to enter into the editor.
Resolution:
Press the F9 key.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT2000 - CASCT3000


CASCT2100I Record initialized

The record has been initialized with the space character.
Resolution:
Press the Add key again to add the record.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT2000 - CASCT3000


CASCT2110E Use CFLE or CFLS transactions to edit remote files

You have tried to edit a remote file but you do not have the authority.
Resolution:
Use CFLS or CFLS to edit the file, logging on if necessary.
Module:
dfhzdfdm
Parent topic: CASCT2000 - CASCT3000


CASCT2200I Fill in data and press Add key

Screen is in add mode, enter the desired information and press Add key again to add record.
Resolution:
Press the Add key again to add the record.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT2000 - CASCT3000


CASCT2300I To copy record, press Add key

To copy record, change the information and press the Add key again.
Resolution:
Press the Add key again to add the record.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT2000 - CASCT3000


CASCT2310I To copy record, change key and press Add key

To copy record, change the key information and press the Add key again.
Resolution:
Press the Add key again to add the record.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT2000 - CASCT3000


CASCT2400I Top of file reached

The beginning of the file has been reached, no more records available in this direction.
Resolution:
Use the Next key.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT2000 - CASCT3000


CASCT2425I Top of record reached

The beginning of the record has been reached, no more pages available in this direction.
Resolution:
Use the Pg Down key.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT2000 - CASCT3000


CASCT2450I Bottom of file reached

The end of the file has been reached, no more records available in this direction.
Resolution:
Use the Prev key.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT2000 - CASCT3000


CASCT2475I Bottom of record reached

The end of the record has been reached, no more pages available in this direction.
Resolution:
Use the Pg Up key.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT2000 - CASCT3000


CASCT3000I Search string not found

The string entered in the search could not be found. Either the number of records or the number of bytes searched are displayed.
Resolution:
Check you have entered the correct search string and re-try necessary.
Module:
dfhzdfdm
Parent topic: CASCT2000 - CASCT3000


CASCT5000 - CASCT6110

  • CASCT5000I Update successful
    Update of this record was successful.
  • CASCT5100I Add successful
    Add of this record was successful.
  • CASCT5110I Page(s) added
    The specified number of pages were added successfully.
  • CASCT6000I Delete successful
    The delete of this record was successful.
  • CASCT6010I Pages(s) deleted
    The specified number of pages were deleted successfully.
  • CASCT6100W Delete requested, press delete key again
    Delete of this record has been requested. This is the confirmation message.
  • CASCT6110W Exit edit without saving? If so, press exit again
    You have pressed the exit key without first saving. If you press the exit key again you will lose all changes. Press clear to cancel this request.
Parent topic: CASCT Error Messages


CASCT5000I Update successful

Update of this record was successful.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT5000 - CASCT6110


CASCT5100I Add successful

Add of this record was successful.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT5000 - CASCT6110


CASCT5110I Page(s) added

The specified number of pages were added successfully.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT5000 - CASCT6110


CASCT6000I Delete successful

The delete of this record was successful.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT5000 - CASCT6110


CASCT6010I Pages(s) deleted

The specified number of pages were deleted successfully.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT5000 - CASCT6110


CASCT6100W Delete requested, press delete key again

Delete of this record has been requested. This is the confirmation message.
Resolution:
Press the delete key again to delete record or press the clear key to cancel.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT5000 - CASCT6110


CASCT6110W Exit edit without saving? If so, press exit again

You have pressed the exit key without first saving. If you press the exit key again you will lose all changes. Press clear to cancel this request.
Resolution:
Press the exit key again to exit editing or press clear key to cancel.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT5000 - CASCT6110


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

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

  • 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.
Module:
dfhgfshr
Destination:
Console and standard error.
Parent topic: CASFC Error Messages


CASFC0002I Fileshare terminated

The Fileshare facility has terminated normally.
Module:
dfhgfshr
Destination:
Console and standard error.
Parent topic: CASFC Error Messages


CASFC0003S Fileshare initialization terminated abnormally

The Fileshare facility terminated during initialization.
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.
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.
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.
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.
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.
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.
Module:
dfhesysp
Destination:
CSFL
Parent topic: CASFC Error Messages


CASFD Error Messages

  • CASFD0001 - CASFD0014
Parent topic: Enterprise Server Error Messages


CASFD0001 - CASFD0014

  • 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.
  • CASFD0008S
    The offline dump requester failed to issue the IMS dump request because the parameter to not locked the shared memory was used.
  • CASFD0009S
    The offline dump requester could not issue an IMS dump request for region region-name. The IMS option was not enabled for the region
  • 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.
  • CASFD0013I
    The offline dump requester issued an IMS dump request for region region-name. The dump went to the normal region dump dataset.
  • 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.
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.
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.
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.
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.
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.
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.
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


CASFD0008S

The offline dump requester failed to issue the IMS dump request because the parameter to not locked the shared memory was used.
System action:
The dump request is aborted
Resolution:
Correct the parameters and retry the operation.
Destination:
standard error.
Module:
dfhgtrtd
Parent topic: CASFD0001 - CASFD0014


CASFD0009S

The offline dump requester could not issue an IMS dump request for region region-name. The IMS option was not enabled for the region
System action:
The dump request is aborted
Resolution:
Correct the installation setup and retry the operation.
Destination:
Standard error.
Module:
dfhgdup
Parent topic: CASFD0001 - CASFD0014


CASFD0010I

The offline dump/trace format request is complete.
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.
System action:
None
Resolution:
None
Destination:
Standard error.
Module:
dfhgdup
Parent topic: CASFD0001 - CASFD0014


CASFD0012E

No input dump/trace dataset could be located.
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


CASFD0013I

The offline dump requester issued an IMS dump request for region region-name. The dump went to the normal region dump dataset.
System action:
The dump request is issued
Resolution:
None
Destination:
Standard error.
Module:
dfhgdup
Parent topic: CASFD0001 - CASFD0014


CASFD0014E

The input Dump/Trace dataset was not generated on the same bitism environment.
System action:
None
Resolution:
Check your current environment.
Destination:
Standard error.
Module:
dfhgdup
Parent topic: CASFD0001 - CASFD0014


CASFF 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'.
  • 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'.
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.
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'.
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'.
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.
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.
Module:
dfhff
Destination:
standard error
Parent topic: CASFF Error Messages


CASIP Error Messages

  • CASIP0005 IMS Message Processing Region started for classes job-classes
    The message processing region was started an is available for processing to process classes job-classes.
  • CASIP0006 IMS Message Processing Region initialization started
    IMS Message Processing process initialization started.
  • CASIP0009 IMS Message Processing Region termination complete
    The message processing region has terminated normally.
  • CASIP0010 Debug IMS Message Processing Region termination complete
    The debug message processing region has terminated normally.
  • CASIP0011 IMS Message Processing Region Control registration failed
    The message processing region has terminated because it was unable to register with the IMS TM Control Process.
  • CASIP0012 IMS Message Processing Region local memory allocation error
    The message processing region has terminated attempting to register with the IMS TM Control Process because of a local storage allocation error.
  • CASIP0013 IMS Message Processing Region registered for classes IMS-Classesname
    The IMS Message Processing region registered with the control region for classes IMS-Classesname.
  • CASIP0023 IMS Message Processing Region definition-name started: class(es) "initiator-classes"
    The IMS Message Processing region was started from definition definition-name and will process messages in classes "initiator-classes".
  • CASIP0024 IMS support not enabled; Start for MPR rejected
    The requested MPR (Message Processing Region) was not started because IMS support is not enabled.
  • CASIP0025 IMS Message Processing Region Control registration failed
    The message processing region has terminated because the required TM Control support was not available or disabled.
  • CASIP0026 IMS Transaction tran-id completed but exceeded its threshold of elapsed-time-threshold seconds
    A transaction completed but exceeded its time threshold.
  • CASIP0031 IMS Message Formatting Services local memory allocation error
    Message Formatting Services has terminated attempting to allocate local storage.
  • CASIP5006 casgate-message
    The MPR IPC process issued a message. The text is casgate-message.
Parent topic: Enterprise Server Error Messages


CASIP0005 IMS Message Processing Region started for classes job-classes

The message processing region was started an is available for processing to process classes job-classes.
Module:
dfheini1
Destination:
ES Console
Parent topic: CASIP Error Messages


CASIP0006 IMS Message Processing Region initialization started

IMS Message Processing process initialization started.
Module:
dfheini1
Destination:
ES Console
Parent topic: CASIP Error Messages


CASIP0009 IMS Message Processing Region termination complete

The message processing region has terminated normally.
System Action:
The process terminates normally.
Resolution:
None.
Module:
casmpr
Destination:
System Console and standard error.
Parent topic: CASIP Error Messages


CASIP0010 Debug IMS Message Processing Region termination complete

The debug message processing region has terminated normally.
System Action:
The process terminates normally.
Resolution:
None.
Module:
casmpr
Destination:
System Console and standard error.
Parent topic: CASIP Error Messages


CASIP0011 IMS Message Processing Region Control registration failed

The message processing region has terminated because it was unable to register with the IMS TM Control Process.
System Action:
The process terminates normally.
Resolution:
Correct the error and restart the system.
Module:
casmpr
Destination:
System Console and standard error.
Parent topic: CASIP Error Messages


CASIP0012 IMS Message Processing Region local memory allocation error

The message processing region has terminated attempting to register with the IMS TM Control Process because of a local storage allocation error.
System Action:
The process terminates normally.
Resolution:
Correct the error and restart the system.
Module:
casmpr
Destination:
System Console and standard error.
Parent topic: CASIP Error Messages


CASIP0013 IMS Message Processing Region registered for classes IMS-Classesname

The IMS Message Processing region registered with the control region for classes IMS-Classesname.
Module:
casmpr
Destination:
ES Console
Parent topic: CASIP Error Messages


CASIP0023 IMS Message Processing Region definition-name started: class(es) "initiator-classes"

The IMS Message Processing region was started from definition definition-name and will process messages in classes "initiator-classes".
Module:
casmgr
Destination:
ES Console
Parent topic: CASIP Error Messages


CASIP0024 IMS support not enabled; Start for MPR rejected

The requested MPR (Message Processing Region) was not started because IMS support is not enabled.
System Action:
the request is rejected.
Resolution:
enable support and retry the operation.
Module:
casmgr/dfheini1
Destination:
ES Console
Parent topic: CASIP Error Messages


CASIP0025 IMS Message Processing Region Control registration failed

The message processing region has terminated because the required TM Control support was not available or disabled.
System Action:
The process terminates normally.
Resolution:
Correct the error and restart the system.
Module:
casmpr
Destination:
System Console and standard error.
Parent topic: CASIP Error Messages


CASIP0026 IMS Transaction tran-id completed but exceeded its threshold of elapsed-time-threshold seconds

A transaction completed but exceeded its time threshold.
System Action:
Warning message logged.
Resolution:
Investigate why threshold was exceeded.
Module:
casmpr
Destination:
System Console
Parent topic: CASIP Error Messages


CASIP0031 IMS Message Formatting Services local memory allocation error

Message Formatting Services has terminated attempting to allocate local storage.
System Action:
The process terminates normally.
Resolution:
Correct the error and restart the system.
Module:
casmfs
Destination:
System Console and standard error.
Parent topic: CASIP Error Messages


CASIP5006 casgate-message

The MPR IPC process issued a message. The text is casgate-message.
System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
casmpr
Destination:
Console
Parent topic: CASIP Error Messages


CASJC Error Messages

  • CASJC0001I Journal control initialized
    The journal control facility is initialized and ready to accept requests.
  • CASJC0002I Journal control terminated
    The journal control facility has terminated normally.
  • CASJC0003S Journal control initialization terminated abnormally
    The journal control facility terminated during initialization.
  • CASJC0004S Critical journal control storage error
    The journal control facility encountered a local storage failure that was not recoverable.
  • CASJC0011I Extra-Partition TD initialized
    The Extra-Partition TD facility is initialized and ready to accept requests.
  • CASJC0012I Extra-Partition TD terminated
    The Extra-Partition TD facility has terminated normally.
  • CASJC0013S Extra-Partition TD initialization terminated abnormally
    The Extra-Partition TD facility terminated during initialization.
  • CASJC0014S Critical Extra-Partition TD storage error
    The Extra-Partition TD facility encountered a local storage failure that was not recoverable.
  • CASJC0015S Journal control failed - local storage allocation error
    The Journal control program could not allocate the required local storage buffering.
  • CASJC0016I Extra-Partition TD recovery initiated
    The Extra-Partition TD program has been restarted after a failure and the new process is recovering pending requests.
  • CASJC0017I Journal control recovery initiated
    The Journal control program has been restarted after a failure and the new process is recovering pending requests.
Parent topic: Enterprise Server Error Messages


CASJC0001I Journal control initialized

The journal control facility is initialized and ready to accept requests.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC Error Messages


CASJC0002I Journal control terminated

The journal control facility has terminated normally.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC Error Messages


CASJC0003S Journal control initialization terminated abnormally

The journal control facility terminated during initialization.
System Action:
The process is terminated. Journal service is not available to the region.
Resolution:
Correct the error and restart the region.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC Error Messages


CASJC0004S Critical journal control storage error

The journal control facility encountered a local storage failure that was not recoverable.
System Action:
The region is terminated abnormally.
Resolution:
Correct the error and restart the region.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC Error Messages


CASJC0011I Extra-Partition TD initialized

The Extra-Partition TD facility is initialized and ready to accept requests.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC Error Messages


CASJC0012I Extra-Partition TD terminated

The Extra-Partition TD facility has terminated normally.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC Error Messages


CASJC0013S Extra-Partition TD initialization terminated abnormally

The Extra-Partition TD facility terminated during initialization.
System Action:
The process is terminated. Journal service is not available to the region.
Resolution:
Correct the error and restart the region.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC Error Messages


CASJC0014S Critical Extra-Partition TD storage error

The Extra-Partition TD facility encountered a local storage failure that was not recoverable.
System Action:
The region is terminated abnormally.
Resolution:
Correct the error and restart the region.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC Error Messages


CASJC0015S Journal control failed - local storage allocation error

The Journal control program could not allocate the required local storage buffering.
System Action:
The porcess is terminated abnormally.
Resolution:
Correct the error and restart the region.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC Error Messages


CASJC0016I Extra-Partition TD recovery initiated

The Extra-Partition TD program has been restarted after a failure and the new process is recovering pending requests.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC Error Messages


CASJC0017I Journal control recovery initiated

The Journal control program has been restarted after a failure and the new process is recovering pending requests.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC Error Messages


CASKC Error Messages

  • CASKC0000 - CASKC0015
  • CASKC0016 - CASKC0030
  • CASKC0031 - CASKC0048
  • CASKC1000 - CASKC1003
  • CASKC5006 - CASKC6008
Parent topic: Enterprise Server Error Messages


CASKC0000 - CASKC0015

  • CASKC0000E
    Transaction trans-id is not defined in the region Program Control Table (PCT).
  • CASKC0001E
    Transaction trans-id abnormally terminated with abend code abend-code. A abend-description will be supplied for standard CICS API exception ABENDs.
  • CASKC0002E
    The system supplied module "dfhzplt.gnt" was not accessible.
  • CASKC0003I
    The server process process-id has shutdown normally.
  • CASKC0004W
    The region manager requested that a CICS server process be started and received an error response.
  • CASKC0005W
    The region manager attempted to close a CICS server process and received an error. This may be due to a lack of shared memory.
  • CASKC0006E
    A CICS API server abended during a transaction. The transaction cannot be continued. The abend could not be handled directly by transaction system.
  • CASKC0007W
    The system shared memory resource limit has been reached. The shared storage cushion will be released and made available to the system. Any GETMAIN SHARED or LOAD HOLD requests will be rejected until the critical memory condition is alleviated. Any tasks which require more storage than is available will will be suspended until the storage requirements can be met.
  • CASKC0008I
    The system has now enough free shared storage to re-acquire the shared storage cushion. GETMAIN SHARED and LOAD HOLD requests will now be accepted.
  • CASKC0009E
    The PCT entry transid is currently marked as disabled.
  • CASKC0010I
    The animation server has shutdown normally. The shutdown was implicitly requested by closing the associated terminal.
  • CASKC0011I
    The destination specified triggering of the transaction on a terminal other than the current terminal in single tasking mode.
  • CASKC0012W
    The system attempted to read an MQ queue record from the queue queue-name. The MQ open opperation failed with reason code reason-code.
  • CASKC0013E
    The system attempted to read an MQ queue record from the queue queue-name. The MQ open opperation failed with reason code reason-code.
  • CASKC0014E
    The system attempted to read an MQ queue record from the queue queue-name. The read opperation failed to return a record.
  • CASKC0015E
    The system attempted to read an MQ queue record from the queue queue-name. The read opperation failed with reason code reason-code.
Parent topic: CASKC Error Messages


CASKC0000E

Transaction trans-id is not defined in the region Program Control Table (PCT).
System action:
The transaction request is reject.
Resolution:
Supply a correct transaction identifier or request that the system administrator add the transaction identifier definition to the region PCT.
Destination:
User terminal
Module:
dfheserv
Parent topic: CASKC0000 - CASKC0015


CASKC0001E

Transaction trans-id abnormally terminated with abend code abend-code. A abend-description will be supplied for standard CICS API exception ABENDs.
System action:
The transaction is terminated and protected resources are returned to the state they were in at the start of the failing transaction.
Resolution:
Correct the cause of the abnormal termination and re-submit the request.
Destination:
User terminal, TDQ CSMT and console.log.
Module:
dfheserv
Parent topic: CASKC0000 - CASKC0015


CASKC0002E

The system supplied module "dfhzplt.gnt" was not accessible.
System action:
The region is terminated immediately.
Resolution:
Correct the setup of the region such that the module can be loaded and re-start the region.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0000 - CASKC0015


CASKC0003I

The server process process-id has shutdown normally.
System action:
The process terminates normally.
Resolution:
None.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0000 - CASKC0015


CASKC0004W

The region manager requested that a CICS server process be started and received an error response.
System action:
Decrement AMAX.
Resolution:
Try increasing the value of AMAX to ascertain whether the problem is permanent.
Destination:
System Console and standard error.
Module:
dfhgglbl
Parent topic: CASKC0000 - CASKC0015


CASKC0005W

The region manager attempted to close a CICS server process and received an error. This may be due to a lack of shared memory.
System action:
Increment AMAX.
Resolution:
Try decreasing the value of AMAX so ascertain whether the problem is permanent.
Destination:
System Console and standard error.
Module:
dfhgglbl
Parent topic: CASKC0000 - CASKC0015


CASKC0006E

A CICS API server abended during a transaction. The transaction cannot be continued. The abend could not be handled directly by transaction system.
System action:
Start a new CICS API server.
Resolution:
Try running the transaction again. If the problem persists then the transaction is probably faulty. Contact the system administrator to get the problem resolved.
Destination:
Terminal
Module:
dfhgglbl
Parent topic: CASKC0000 - CASKC0015


CASKC0007W

The system shared memory resource limit has been reached. The shared storage cushion will be released and made available to the system. Any GETMAIN SHARED or LOAD HOLD requests will be rejected until the critical memory condition is alleviated. Any tasks which require more storage than is available will will be suspended until the storage requirements can be met.
System action:
Make the shared storage cushion available and suspend any tasks which require more memory than is available until their requirements can be met.
Resolution:
If this is a common occurrence increase the number of shared pages in the SIT.
Destination:
System Console.
Module:
dfhgglbl
Parent topic: CASKC0000 - CASKC0015


CASKC0008I

The system has now enough free shared storage to re-acquire the shared storage cushion. GETMAIN SHARED and LOAD HOLD requests will now be accepted.
System action:
The shared storage cushion will be re-acquired and the critical memory condition will be reset.
Resolution:
None
Destination:
System Console.
Module:
dfhgglbl
Parent topic: CASKC0000 - CASKC0015


CASKC0009E

The PCT entry transid is currently marked as disabled.
System action:
The requested transaction is not executed.
Resolution:
Notify the system administrator.
Destination:
User terminal and TDQ CSMT.
Module:
dfheserv
Parent topic: CASKC0000 - CASKC0015


CASKC0010I

The animation server has shutdown normally. The shutdown was implicitly requested by closing the associated terminal.
System action:
The process terminates normally.
Resolution:
None.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0000 - CASKC0015


CASKC0011I

The destination specified triggering of the transaction on a terminal other than the current terminal in single tasking mode.
System action:
None.
Resolution:
None.
Destination:
System Console and CSMT td queue.
Module:
dfhetstd
Parent topic: CASKC0000 - CASKC0015


CASKC0012W

The system attempted to read an MQ queue record from the queue queue-name. The MQ open opperation failed with reason code reason-code.
System action:
Transaction aborted. The MQ Message is retained on the input queue queue-name.
Resolution:
Resolve the configuration mismatch and restart the associated ASEE iniation queue listener.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0000 - CASKC0015


CASKC0013E

The system attempted to read an MQ queue record from the queue queue-name. The MQ open opperation failed with reason code reason-code.
System action:
Transaction aborted. The MQ Message is retained on the input queue queue-name.
Resolution:
Resolve the configuration mismatch and restart the associated ASEE iniation queue listener.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0000 - CASKC0015


CASKC0014E

The system attempted to read an MQ queue record from the queue queue-name. The read opperation failed to return a record.
System action:
Transaction aborted.
Resolution:
Resolve the configuration mismatch and restart the associated ASEE iniation queue listener.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0000 - CASKC0015


CASKC0015E

The system attempted to read an MQ queue record from the queue queue-name. The read opperation failed with reason code reason-code.
System action:
Transaction aborted.
Resolution:
Resolve the configuration mismatch and restart the associated ASEE iniation queue listener.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0000 - CASKC0015


CASKC0016 - CASKC0030

  • CASKC0016E
    The system attempted to read an MQ queue record from the queue queue-name. The close opperation for the queue failed with reason code reason-code. This error should not occur.
  • CASKC0017E
    The system attempted to register the request-handler-name request handler. The MF RTS return code is reason-code. Services requiring this handler will not be available until the problem is corrected. The MF RTS may not be able to locate the executable or.
  • CASKC0018E
    The system attempted load the Interface Definition Table (IDT) for Service service-name. The file system open for the disk image failed with a reason code of reason-code. The reason-code will be displayed in decimal. The hexidecimal representation of the error might indicate a COBOL RTS error, for example 0x390D is a 9/13 which means file not found.
  • CASKC0019E
    The system attempted to load the Interface Definition Table (IDT) for Service service-name. The file system read for the disk image details failed with a reason code of reason-code.
  • CASKC0020E
    The system attempted to load the Interface Definition Table (IDT) for Service service-name. The allocate request for storage to hold the disk image failed with a reason code of reason-code.
  • CASKC0021E
    The system attempted to load the Interface Definition Table (IDT) for Service service-name. The file system read for the disk image failed with a reason code of reason-code.
  • CASKC0022E
    The system could not connect to the queue-manager-name queue manager. The reason code is reason-code.
  • CASKC0023E
    The system could not locate a definition for the request-handler-name request handler.
  • CASKC0024E
    The request handler did not generate a response to an input request.
  • CASKC0025I
    A message has been generated processing a service.
  • CASKC0026E
    A message has been generated processing a service.
  • CASKC0027E
    A message has been generated processing a service.
  • CASKC0028E
    A message has been generated processing a service.
  • CASKC0029E
    A message has been generated processing a service.
  • CASKC0030S
    One of the essential system modules failed to load.
Parent topic: CASKC Error Messages


CASKC0016E

The system attempted to read an MQ queue record from the queue queue-name. The close opperation for the queue failed with reason code reason-code. This error should not occur.
System action:
None.
Resolution:
Report error to Micro Focus.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0016 - CASKC0030


CASKC0017E

The system attempted to register the request-handler-name request handler. The MF RTS return code is reason-code. Services requiring this handler will not be available until the problem is corrected. The MF RTS may not be able to locate the executable or.
System action:
None.
Resolution:
Correct the error and re-register the handler.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0016 - CASKC0030


CASKC0018E

The system attempted load the Interface Definition Table (IDT) for Service service-name. The file system open for the disk image failed with a reason code of reason-code. The reason-code will be displayed in decimal. The hexidecimal representation of the error might indicate a COBOL RTS error, for example 0x390D is a 9/13 which means file not found.
System action:
The service request is failed
Resolution:
Correct the location or deployment error and retry the request.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0016 - CASKC0030


CASKC0019E

The system attempted to load the Interface Definition Table (IDT) for Service service-name. The file system read for the disk image details failed with a reason code of reason-code.
System action:
The service request is failed
Resolution:
Correct the location or deployment error and retry the request.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0016 - CASKC0030


CASKC0020E

The system attempted to load the Interface Definition Table (IDT) for Service service-name. The allocate request for storage to hold the disk image failed with a reason code of reason-code.
System action:
The service request is failed
Resolution:
Increase the shared memory allocation for the Cobol Application Server.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0016 - CASKC0030


CASKC0021E

The system attempted to load the Interface Definition Table (IDT) for Service service-name. The file system read for the disk image failed with a reason code of reason-code.
System action:
The service request is failed
Resolution:
Correct the location or deployment error and retry the request.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0016 - CASKC0030


CASKC0022E

The system could not connect to the queue-manager-name queue manager. The reason code is reason-code.
System action:
This request will be aborted.
Resolution:
Check the MQ and CAS configuration.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0016 - CASKC0030


CASKC0023E

The system could not locate a definition for the request-handler-name request handler.
System action:
All requests associated with this handler will be rejected.
Resolution:
Check the CAS configuration.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0016 - CASKC0030


CASKC0024E

The request handler did not generate a response to an input request.
System action:
Active work unit will be terminated.
Resolution:
Check that the request handler is working properly.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0016 - CASKC0030


CASKC0025I

A message has been generated processing a service.
System action:
None.
Resolution:
None
Destination:
System Console
Module:
dfheserv
Parent topic: CASKC0016 - CASKC0030


CASKC0026E

A message has been generated processing a service.
System action:
None.
Resolution:
None
Destination:
System Console
Module:
dfheserv, casbat, casmpr
Parent topic: CASKC0016 - CASKC0030


CASKC0027E

A message has been generated processing a service.
System action:
None.
Resolution:
None
Destination:
System Console
Module:
dfheserv
Parent topic: CASKC0016 - CASKC0030


CASKC0028E

A message has been generated processing a service.
System action:
None.
Resolution:
None
Destination:
System Console
Module:
dfheserv
Parent topic: CASKC0016 - CASKC0030


CASKC0029E

A message has been generated processing a service.
System action:
None.
Resolution:
None
Destination:
System Console
Module:
dfheserv
Parent topic: CASKC0016 - CASKC0030


CASKC0030S

One of the essential system modules failed to load.
System action:
The internal service request will not be processed.
Resolution:
Ensure product is installed correctly. A forced shutdown could be required to terminate the server.
Destination:
System Console
Module:
dfheserv
Parent topic: CASKC0016 - CASKC0030


CASKC0031 - CASKC0048

  • CASKC0031E
    The system attempted load the Interface Definition Table (IDT) but failed to locate the file. IDT locations need to be fully qualified.
  • CASKC0032I
    A security profile Security profile found for Queue Manager Queue Manager Name has been found and security for WebSphere MQ has been turned off.
  • CASKC0033I
    A security profile Security profile found for Queue Manager Queue Manager Name has not been found and security for WebSphere MQ has been turned on.
  • CASKC0034I
    A security profile Security profile found for Queue Manager Queue Manager Namehas not been found and security for MQSeries has been turned on for type Type security.
  • CASKC0035I
    A security profile Security profile found for Queue Manager Queue Manager Namehas been found and security for WebSphere MQ has been turned off for type Type security.
  • CASKC0040I
    A remote client entered a message to the active system.
  • CASKC0041E
    Transaction trans-id abnormally terminated with abend code abend-code. A abend-description will be supplied for standard CICS API exception ABENDs.
  • CASKC0042I
    Transaction trans-id abnormally terminated with abend code abend-code. A abend-description will be supplied for standard CICS API exception ABENDs.
  • CASKC0043E
    Transaction trans-id abnormally terminated with abend code ASRA.
  • CASKC0044S
    ES failed to authorize the CICS Default user during initialization.
  • CASKC0045I
    Logging all enable and disable requests for CICS transactions
  • CASKC0046I User (user-id) requested (request type) on Program (program-id for request) from Tran (active trans-id) Terminal(terminal id) Return-code(return-code).
    Logging all newcopy/phasein/cancel requests for CICS transactions.
  • CASKC0047S ES failed to authorize ESMAC Default user default-user
    ES failed to authorize the CICS Default user during initialization.
  • CASKC0048S Process process-id of the process that is killed hard-killed. System dump issued
    Process soft-kill failed and was hard-killed.
Parent topic: CASKC Error Messages


CASKC0031E

The system attempted load the Interface Definition Table (IDT) but failed to locate the file. IDT locations need to be fully qualified.
System action:
The service request is failed
Resolution:
Correct the location or deployment error and retry the request.
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC0031 - CASKC0048


CASKC0032I

A security profile Security profile found for Queue Manager Queue Manager Name has been found and security for WebSphere MQ has been turned off.
System action:
None.
Resolution:
None
Destination:
System Console
Module:
dfheserv
Parent topic: CASKC0031 - CASKC0048


CASKC0033I

A security profile Security profile found for Queue Manager Queue Manager Name has not been found and security for WebSphere MQ has been turned on.
System action:
None
Resolution:
None
Destination:
System Console
Module:
dfheserv
Parent topic: CASKC0031 - CASKC0048


CASKC0034I

A security profile Security profile found for Queue Manager Queue Manager Namehas not been found and security for MQSeries has been turned on for type Type security.
System action:
None.
Resolution:
None
Destination:
System Console
Module:
dfheserv
Parent topic: CASKC0031 - CASKC0048


CASKC0035I

A security profile Security profile found for Queue Manager Queue Manager Namehas been found and security for WebSphere MQ has been turned off for type Type security.
System action:
None.
Resolution:
None
Destination:
System Console
Module:
dfheserv
Parent topic: CASKC0031 - CASKC0048


CASKC0040I

A remote client entered a message to the active system.
System action:
None.
Resolution:
None
Destination:
System Console
Module:
casasys
Parent topic: CASKC0031 - CASKC0048


CASKC0041E

Transaction trans-id abnormally terminated with abend code abend-code. A abend-description will be supplied for standard CICS API exception ABENDs.
System action:
The transaction is terminated.
Resolution:
Correct the cause of the abnormal termination and re-submit the request.
Destination:
console.log
Module:
dfhgglbl
Parent topic: CASKC0031 - CASKC0048


CASKC0042I

Transaction trans-id abnormally terminated with abend code abend-code. A abend-description will be supplied for standard CICS API exception ABENDs.
System action:
The transaction is terminated and protected resources are returned to the state they were in at the start of the failing transaction.
Resolution:
Correct the cause of the abnormal termination and re-submit the request.
Destination:
User terminal ,TDQ CSMT and console.log.
Module:
dfheserv
Parent topic: CASKC0031 - CASKC0048


CASKC0043E

Transaction trans-id abnormally terminated with abend code ASRA.
System action:
The transaction is terminated and protected resources are returned to the state they were in at the start of the failing transaction.
Resolution:
Correct the cause of the abnormal termination and re-submit the request.
Destination:
User terminal ,TDQ CSMT and console.log.
Module:
dfhebms
Parent topic: CASKC0031 - CASKC0048


CASKC0044S

ES failed to authorize the CICS Default user during initialization.
System action:
ES shutdown is initialized
Resolution:
Correct authorization problem for default CICS user
Destination:
System Console
Module:
dfheserv
Parent topic: CASKC0031 - CASKC0048


CASKC0045I

Logging all enable and disable requests for CICS transactions
System action:
none
Resolution:
none
Destination:
CSKL
Module:
dfhesysp
Parent topic: CASKC0031 - CASKC0048


CASKC0046I User (user-id) requested (request type) on Program (program-id for request) from Tran (active trans-id) Terminal(terminal id) Return-code(return-code).

Logging all newcopy/phasein/cancel requests for CICS transactions.
Module:
dfhesysp
Destination:
CSMT and console.log
Parent topic: CASKC0031 - CASKC0048


CASKC0047S ES failed to authorize ESMAC Default user default-user

ES failed to authorize the CICS Default user during initialization.
System Action:
ES shutdown is initialized.
Resolution:
Correct authorization problem for default ESMAC user.
Module:
dfheserv
Destination:
System Console
Parent topic: CASKC0031 - CASKC0048


CASKC0048S Process process-id of the process that is killed hard-killed. System dump issued

Process soft-kill failed and was hard-killed.
System Action:
System dump taken.
Resolution:
Correct the cause of the abnormal termination and re-submit the request.
Module:
dfhgglbl
Destination:
System Console
Parent topic: CASKC0031 - CASKC0048


CASKC1000 - CASKC1003

  • CASKC1000I
    During startup the maximum number of concurrent requests is logged.
  • CASKC1001W
    The number of active client requests exceeded the licensed maximum client-count times.
  • CASKC1002I
    During shutdown the maximum number of concurrent requests is logged against the actual recorded peak.
  • CASKC1003I
    A request for a license of the referenced type was made to the license server. No license was available. Please contact your Micro Focus sales representative.
Parent topic: CASKC Error Messages


CASKC1000I

During startup the maximum number of concurrent requests is logged.
System action:
None
Resolution:
None
Destination:
System Console and standard error.
Module:
dfhgglbl
Parent topic: CASKC1000 - CASKC1003


CASKC1001W

The number of active client requests exceeded the licensed maximum client-count times.
System action:
System will continue as normal
Resolution:
Check system configuration and allocate additional client licenses as appropriate
Destination:
System Console and standard error.
Module:
dfhgglbl
Parent topic: CASKC1000 - CASKC1003


CASKC1002I

During shutdown the maximum number of concurrent requests is logged against the actual recorded peak.
System action:
None
Resolution:
None
Destination:
System Console and standard error.
Module:
dfhgglbl
Parent topic: CASKC1000 - CASKC1003


CASKC1003I

A request for a license of the referenced type was made to the license server. No license was available. Please contact your Micro Focus sales representative.
System action:
None
Resolution:
None
Destination:
System Console and standard error.
Module:
dfheserv
Parent topic: CASKC1000 - CASKC1003


CASKC5006 - CASKC6008

  • CASKC5006I
    The SEP, Batch Initiator or IMS MPR process issued a message. The text is message.
  • CASKC6001S
    A process was looping or hung and exceeded the specified task timeout. The attempt to kill the process aparently has failed to remove the process.
  • CASKC6002I
    A process was looping or hung and exceeded the specified TIME parameter on the JOB or STEP card.
  • CASKC6003I
    A transaction exceeded its time threshold and is still running.
  • CASKC6004I
    A transaction completed but exceeded its time threshold.
  • CASKC6005I
    An IMS transaction exceeded its time threshold and is still running.
  • CASKC6006I
    Time taken by the web service application was greater than ES_WS_RUNAWAY_TIMEOUT
  • CASKC6007I IMS Transaction tran-id has exceeded its processing limit of processing limit in seconds seconds
    An IMS transaction has exceeded its processing limit and is still running.
  • CASKC6008S No reply received for lock request from process-id. GLM work halted until reply on ESMAC control page is provided.
    A process was looping or hung and exceeded the specified task timeout. The attempt to kill the process aparently has failed to remove the process.
Parent topic: CASKC Error Messages


CASKC5006I

The SEP, Batch Initiator or IMS MPR process issued a message. The text is message.
System action:
Dependant on the message.
Resolution:
Action the message
Destination:
Console
Module:
cascpsrv
Parent topic: CASKC5006 - CASKC6008


CASKC6001S

A process was looping or hung and exceeded the specified task timeout. The attempt to kill the process aparently has failed to remove the process.
System action:
The process DCA is released and internal recovery is initiated.
Resolution:
Resolve the issue that caused the timeout
Destination:
System Console
Module:
casmgr
Parent topic: CASKC5006 - CASKC6008


CASKC6002I

A process was looping or hung and exceeded the specified TIME parameter on the JOB or STEP card.
System action:
The process DCA is released and internal recovery is initiated.
Resolution:
Resolve the issue that caused the timeout
Destination:
System Console
Module:
casmgr
Parent topic: CASKC5006 - CASKC6008


CASKC6003I

A transaction exceeded its time threshold and is still running.
System action:
Warning message logged.
Resolution:
Investigate why threshold was exceeded
Destination:
System Console
Module:
casmgr
Parent topic: CASKC5006 - CASKC6008


CASKC6004I

A transaction completed but exceeded its time threshold.
System action:
Warning message logged.
Resolution:
Investigate why threshold was exceeded
Destination:
System Console
Module:
dfheserv
Parent topic: CASKC5006 - CASKC6008


CASKC6005I

An IMS transaction exceeded its time threshold and is still running.
System action:
Warning message logged.
Resolution:
Investigate why threshold was exceeded
Destination:
System Console
Module:
casmgr
Parent topic: CASKC5006 - CASKC6008


CASKC6006I

Time taken by the web service application was greater than ES_WS_RUNAWAY_TIMEOUT
System action:
System will continue as normal.
Resolution:
Resolve the issue that caused the timeout.
Destination:
Console and standard error
Module:
cashtsrv
Parent topic: CASKC5006 - CASKC6008


CASKC6007I IMS Transaction tran-id has exceeded its processing limit of processing limit in seconds seconds

An IMS transaction has exceeded its processing limit and is still running.
System Action:
Log message and abend transaction.
Resolution:
Investigate why the processing limit was exceeded.
Module:
casmgr
Destination:
System Console
Parent topic: CASKC5006 - CASKC6008


CASKC6008S No reply received for lock request from process-id. GLM work halted until reply on ESMAC control page is provided.

A process was looping or hung and exceeded the specified task timeout. The attempt to kill the process aparently has failed to remove the process.
System Action:
The process DCA is released and internal recovery is initiated.
Resolution:
Resolve the issue that caused the timeout.
Module:
casmgr
Destination:
System Console
Parent topic: CASKC5006 - CASKC6008


CASMG Error Message

  • CASMG9999E message-number, message-insert , message-insert ...
    The system could not locate a message in the message file so displayed a standard message number. The original message number, and any message inserts are included in the message text.
Parent topic: Enterprise Server Error Messages


CASMG9999E message-number, message-insert , message-insert ...

The system could not locate a message in the message file so displayed a standard message number. The original message number, and any message inserts are included in the message text.
Resolution:
Check online help for information on the missing message.
Destination:
Stdout
Module:
any
Parent topic: CASMG Error Message


CASMQ Error Messages

  • CASMQ1001 - CASMQ1009
  • CASMQ1010 - CASMQ1019
  • CASMQ1020 - CASMQ1031
  • CASMQ5001 - CASMQ5011
  • CASMQ5059 - CASMQ5069
  • CASMQ5070 - CASMQ5079
  • CASMQ5080 - CASMQ5087
Parent topic: Enterprise Server Error Messages


CASMQ1001 - CASMQ1009

  • CASMQ1001I Connection to WebSphere MQ re-established.
    The WebSphere MQ trigger monitor program (CKTI) has re-established the connection to the MQ server. CKTI will continue triggering transactions.
  • CASMQ1002E Connection to WebSphere MQ lost, RC = reason-code, retrying...
    The WebSphere MQ trigger monitor program (CKTI) has lost the connection to the MQ server. CKTI will retry to connect in the background.
  • CASMQ1003E Failed to start transaction transaction from CKTI
    The WebSphere MQ trigger monitor program (CKTI) has failed to start the CICS transaction specified from the initiation queue message process definition.
  • CASMQ1004E Unexpected error reason from MQGET in CKTI, RC = reason-code
    The WebSphere MQ trigger monitor program (CKTI) has received an unexpected reason code from a MQGET API call.
  • CASMQ1005E Unable to start trigger transaction trans-id, reason = reason-code
    The WebSphere MQ trigger monitor program (CKTI) could not start the transaction defined in the WebSphere MQ trigger process definition. The transaction may not be defined to the local system.
  • CASMQ1006E Unexpected message format (msg-format) on MQGET in CKTI
    The WebSphere MQ trigger monitor program (CKTI) was expecting a trigger message (MQFMT-TRIGGER) but received an unexpected format.
  • CASMQ1007E Unexpected application type (appltype) on MQGET in CKTI
    The WebSphere MQ trigger monitor program (CKTI) was expecting an application type of CICS (MQAT-CICS) but received an unexpected appltype.
  • CASMQ1008I IMS Trigger Monitor initialization completed
    The IMS WebSphere MQ Trigger Monitor successfully initialized.
  • CASMQ1009I IMS Trigger Monitor is ready, initiation queue: initiation-queue-name
    The IMS WebSphere MQ Trigger Monitor is ready to process user requests.
Parent topic: CASMQ Error Messages


CASMQ1001I Connection to WebSphere MQ re-established.

The WebSphere MQ trigger monitor program (CKTI) has re-established the connection to the MQ server. CKTI will continue triggering transactions.
Module:
dfhtmqgw
Destination:
Console
Parent topic: CASMQ1001 - CASMQ1009


CASMQ1002E Connection to WebSphere MQ lost, RC = reason-code, retrying...

The WebSphere MQ trigger monitor program (CKTI) has lost the connection to the MQ server. CKTI will retry to connect in the background.
Module:
dfhtmqgw
Destination:
Console
Parent topic: CASMQ1001 - CASMQ1009


CASMQ1003E Failed to start transaction transaction from CKTI

The WebSphere MQ trigger monitor program (CKTI) has failed to start the CICS transaction specified from the initiation queue message process definition.
Module:
dfhtmqgw
Destination:
Console
Parent topic: CASMQ1001 - CASMQ1009


CASMQ1004E Unexpected error reason from MQGET in CKTI, RC = reason-code

The WebSphere MQ trigger monitor program (CKTI) has received an unexpected reason code from a MQGET API call.
Module:
dfhtmqgw
Destination:
Console
Parent topic: CASMQ1001 - CASMQ1009


CASMQ1005E Unable to start trigger transaction trans-id, reason = reason-code

The WebSphere MQ trigger monitor program (CKTI) could not start the transaction defined in the WebSphere MQ trigger process definition. The transaction may not be defined to the local system.
System Action:
No transaction will be started.
Resolution:
Make sure that the transaction is defined correctly within the WebSphere MQ process definition and is defined as a local transaction to the CICS region.
Module:
dfhtmqgw
Destination:
Console
Parent topic: CASMQ1001 - CASMQ1009


CASMQ1006E Unexpected message format (msg-format) on MQGET in CKTI

The WebSphere MQ trigger monitor program (CKTI) was expecting a trigger message (MQFMT-TRIGGER) but received an unexpected format.
System Action:
Trigger transaction will not be started.
Resolution:
Check the WebSphere MQ Process definition.
Module:
dfhtmqgw
Destination:
Console
Parent topic: CASMQ1001 - CASMQ1009


CASMQ1007E Unexpected application type (appltype) on MQGET in CKTI

The WebSphere MQ trigger monitor program (CKTI) was expecting an application type of CICS (MQAT-CICS) but received an unexpected appltype.
System Action:
Trigger transaction will not be started.
Resolution:
Check the WebSphere MQ Process definition.
Module:
dfhtmqgw
Destination:
Console
Parent topic: CASMQ1001 - CASMQ1009


CASMQ1008I IMS Trigger Monitor initialization completed

The IMS WebSphere MQ Trigger Monitor successfully initialized.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1001 - CASMQ1009


CASMQ1009I IMS Trigger Monitor is ready, initiation queue: initiation-queue-name

The IMS WebSphere MQ Trigger Monitor is ready to process user requests.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1001 - CASMQ1009


CASMQ1010 - CASMQ1019

  • CASMQ1010I IMS Trigger Monitor terminated
    The IMS WebSphere MQ Trigger Monitor terminated.
  • CASMQ1011E Unexpected error while connecting to queue manager queue-manager-name in IMS Trigger Monitor, status: status-code
    The IMS Trigger Monitor received an error trying to connect to the Queue Manager.
  • CASMQ1012E Unexpected error while opening initiation queue initiation-queue-name in IMS Trigger Monitor, status: status-code
    The IMS Trigger Monitor received an error trying to open the initiation queue.
  • CASMQ1013E Unexpected error while getting message from the initiation queue initiation-queue-name in IMS Trigger Monitor, status: status-code
    The IMS Trigger Monitor received an error retrieving a message token from the initiation queue that is being monitored.
  • CASMQ1014E Unexpected error while closing initiation queue initiation-queue-name in IMS Trigger Monitor, status: status-code
    The IMS Trigger Monitor could not close the initiation queue during termination.
  • CASMQ1015E Unexpected error while disconnecting from queue manager queue-manager-name in IMS Trigger Monitor, status: status-code
    An error was received during termination when the IMS Trigger Monitor attempted to disconnect from the Queue Manager.
  • CASMQ1016E Unexpected application type appltype on MQGET in IMS Trigger Monitor
    The IMS WebSphere MQ Trigger Monitor was expecting an application type of IMS (MQAT-IMS) but received an unexpected appltype.
  • CASMQ1017E Unexpected MQ message version message-version in IMS Trigger Monitor
    The IMS WebSphere MQ Trigger Monitor program (CSQ4TRMN) was expecting an MQ message version 1 (MQTM-VERSION-1) but received an unexpected version.
  • CASMQ1018E Unexpected MQ message structid mqtm-strucid in IMS Trigger Monitor
    The IMS WebSphere MQ Trigger Monitor program (CSQ4TRMN) was expecting a message with mqtm strucid of (MQTM-STRUC-ID) but received an unexpected mqtm strucid.
  • CASMQ1019E Unexpected error from IMS SYNC call, status code: status-code
    An IMS SYNC issued by the IMS Trigger Monitor has failed.
Parent topic: CASMQ Error Messages


CASMQ1010I IMS Trigger Monitor terminated

The IMS WebSphere MQ Trigger Monitor terminated.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1010 - CASMQ1019


CASMQ1011E Unexpected error while connecting to queue manager queue-manager-name in IMS Trigger Monitor, status: status-code

The IMS Trigger Monitor received an error trying to connect to the Queue Manager.
System Action:
The IMS Trigger Monitor is terminated.
Resolution:
Ensure that the Queue Manager in the Trigger Monitor startup JCL is correct.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1010 - CASMQ1019


CASMQ1012E Unexpected error while opening initiation queue initiation-queue-name in IMS Trigger Monitor, status: status-code

The IMS Trigger Monitor received an error trying to open the initiation queue.
System Action:
The IMS Trigger Monitor is terminated.
Resolution:
Ensure that the initiation queue in the Trigger Monitor startup JCL is correct and that the initiation queue has been defined.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1010 - CASMQ1019


CASMQ1013E Unexpected error while getting message from the initiation queue initiation-queue-name in IMS Trigger Monitor, status: status-code

The IMS Trigger Monitor received an error retrieving a message token from the initiation queue that is being monitored.
System Action:
The message token on the initiation queue will not be processed.
Resolution:
Check the completion and reason code to determine the cause of the error displayed in the message.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1010 - CASMQ1019


CASMQ1014E Unexpected error while closing initiation queue initiation-queue-name in IMS Trigger Monitor, status: status-code

The IMS Trigger Monitor could not close the initiation queue during termination.
Resolution:
Check the completion and reason code to determine the cause of the error.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1010 - CASMQ1019


CASMQ1015E Unexpected error while disconnecting from queue manager queue-manager-name in IMS Trigger Monitor, status: status-code

An error was received during termination when the IMS Trigger Monitor attempted to disconnect from the Queue Manager.
Resolution:
Check the completion and reason code to determine the cause of the error.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1010 - CASMQ1019


CASMQ1016E Unexpected application type appltype on MQGET in IMS Trigger Monitor

The IMS WebSphere MQ Trigger Monitor was expecting an application type of IMS (MQAT-IMS) but received an unexpected appltype.
System Action:
he transaction specified in the WebSphere MQ process definition will not be started.
Resolution:
Check the WebSphere MQ Process definition.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1010 - CASMQ1019


CASMQ1017E Unexpected MQ message version message-version in IMS Trigger Monitor

The IMS WebSphere MQ Trigger Monitor program (CSQ4TRMN) was expecting an MQ message version 1 (MQTM-VERSION-1) but received an unexpected version.
System Action:
Trigger transaction will not be started.
Resolution:
Check the WebSphere MQ Process definition.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1010 - CASMQ1019


CASMQ1018E Unexpected MQ message structid mqtm-strucid in IMS Trigger Monitor

The IMS WebSphere MQ Trigger Monitor program (CSQ4TRMN) was expecting a message with mqtm strucid of (MQTM-STRUC-ID) but received an unexpected mqtm strucid.
System Action:
Trigger transaction will not be started.
Resolution:
Check the WebSphere MQ Process definition.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1010 - CASMQ1019


CASMQ1019E Unexpected error from IMS SYNC call, status code: status-code

An IMS SYNC issued by the IMS Trigger Monitor has failed.
Resolution:
Check the status code to determine the cause of the error.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1010 - CASMQ1019


CASMQ1020 - CASMQ1031

  • CASMQ1020E Unexpected error from IMS CHNG call, status code: status-code
    An IMS CHNG issued by the IMS Trigger Monitor has failed.
  • CASMQ1021E Unexpected error from IMS ISRT call, status code: status-code
    An IMS ISRT call issued by the IMS Trigger Monitor has failed.
  • CASMQ1022E Unexpected error from IMS PURG call, status code: status-code
    An IMS PURG call issued by the IMS Trigger Monitor has failed.
  • CASMQ1023I Missing queue manager name, will try using the default queue manager
    A WebSphere MQ Queue Manager name was not specified in the IMS Trigger Monitor startup JCL.
  • CASMQ1024E Missing initiation queue name
    A WebSphere MQ initiation queue name was not specified in the IMS Trigger Monitor startup JCL.
  • CASMQ1025E Unexpected error while connecting to queue manager queue-manager-name in the IMS Trigger Monitor, status: status-code
    he IMS Trigger Monitor received an error trying to connect to the Queue Manager.
  • CASMQ1026E Unexpected error while opening initiation queue initiation-queue-name in the IMS Trigger Monitor, status: status-code
    The IMS Trigger Monitor received an error trying to open the initiation queue.
  • CASMQ1027E Unexpected error while putting message into the initiation queue initiation-queue-name in IMS Trigger Monitor, status: status-code
    The IMS Trigger Monitor received an error placing a message token into the initiation queue that is being monitored.
  • CASMQ1028E Unexpected error while closing initiation queue initiation-queue-name in IMS Trigger Monitor, status: status-code
    The IMS Trigger Monitor could not close the initiation queue during termination.
  • CASMQ1029 message
    An error message generated from the IMS Trigger Monitor.
  • CASMQ1030E Unexpected error while issuing MQCMIT call queue-manager-name in IMS Trigger Monitor, status: status-code
    The IMS Trigger Monitor could not successfully issue a call to commit the WebSphere MQ trigger token message after invoking the end user IMS program.
  • CASMQ1031I IMS-MQ Listener status "status-code" reported for queue trigger-queue on queue manager queue-manager-name
    The MQ-IMS listener for the named trigger queue reported the noted status after a request was sent to start the listener.
Parent topic: CASMQ Error Messages


CASMQ1020E Unexpected error from IMS CHNG call, status code: status-code

An IMS CHNG issued by the IMS Trigger Monitor has failed.
System Action:
Trigger transaction will not be started.
Resolution:
Check the status code to determine the cause of the error.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1020 - CASMQ1031


CASMQ1021E Unexpected error from IMS ISRT call, status code: status-code

An IMS ISRT call issued by the IMS Trigger Monitor has failed.
System Action:
Trigger transaction will not be started.
Resolution:
Check the status code to determine the cause of the error.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1020 - CASMQ1031


CASMQ1022E Unexpected error from IMS PURG call, status code: status-code

An IMS PURG call issued by the IMS Trigger Monitor has failed.
Resolution:
Check the status code to determine the cause of the error.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1020 - CASMQ1031


CASMQ1023I Missing queue manager name, will try using the default queue manager

A WebSphere MQ Queue Manager name was not specified in the IMS Trigger Monitor startup JCL.
System Action:
The IMS Trigger Monitor will try using the default queue manager.
Resolution:
Specify a valid WebSphere MQ Queue Manager name in the IMS Trigger Monitor startup JCL.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1020 - CASMQ1031


CASMQ1024E Missing initiation queue name

A WebSphere MQ initiation queue name was not specified in the IMS Trigger Monitor startup JCL.
System Action:
The IMS Trigger Monitor is not started.
Resolution:
Specify a valid WebSphere MQ initiation queue name in the IMS Trigger Monitor startup JCL.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1020 - CASMQ1031


CASMQ1025E Unexpected error while connecting to queue manager queue-manager-name in the IMS Trigger Monitor, status: status-code

he IMS Trigger Monitor received an error trying to connect to the Queue Manager.
System Action:
The IMS Trigger Monitor is not terminated.
Resolution:
Ensure that the Queue Manager in the Trigger Monitor startup JCL is correct.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1020 - CASMQ1031


CASMQ1026E Unexpected error while opening initiation queue initiation-queue-name in the IMS Trigger Monitor, status: status-code

The IMS Trigger Monitor received an error trying to open the initiation queue.
System Action:
The IMS Trigger Monitor is not terminated.
Resolution:
Ensure that the initiation queue in the Trigger Monitor startup JCL is correct and that the initiation queue has been defined.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1020 - CASMQ1031


CASMQ1027E Unexpected error while putting message into the initiation queue initiation-queue-name in IMS Trigger Monitor, status: status-code

The IMS Trigger Monitor received an error placing a message token into the initiation queue that is being monitored.
System Action:
The message token will not be placed into the initiation queue.
Resolution:
Check the completion and reason code to determine the cause of the error displayed in the message.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1020 - CASMQ1031


CASMQ1028E Unexpected error while closing initiation queue initiation-queue-name in IMS Trigger Monitor, status: status-code

The IMS Trigger Monitor could not close the initiation queue during termination.
Resolution:
Check the completion and reason code to determine the cause of the error.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1020 - CASMQ1031


CASMQ1029 message

An error message generated from the IMS Trigger Monitor.
Resolution:
Check the error message and take appropriate action.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1020 - CASMQ1031


CASMQ1030E Unexpected error while issuing MQCMIT call queue-manager-name in IMS Trigger Monitor, status: status-code

The IMS Trigger Monitor could not successfully issue a call to commit the WebSphere MQ trigger token message after invoking the end user IMS program.
Resolution:
Check the completion and reason code to determine the cause of the error.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1020 - CASMQ1031


CASMQ1031I IMS-MQ Listener status "status-code" reported for queue trigger-queue on queue manager queue-manager-name

The MQ-IMS listener for the named trigger queue reported the noted status after a request was sent to start the listener.
Resolution:
Check the status-code and take action as needed.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1020 - CASMQ1031


CASMQ5001 - CASMQ5011

  • CASMQ5001I ES MQ Service Process initialization started<
    The server ES MQ Service Process initialization has started.
  • CASMQ5002S ES MQ Service Process is not running in multi-threaded mode
    The ES MQ Service Process has not started with the required underlying thread support.
  • CASMQ5003I ES MQ Service Process initialization complete
    The ES MQ Service Process has completed initialization.
  • CASMQ5004S ES MQ Service Process registration failed, reason = reason-code
    The ES MQ Service Process failed registration. The reason code is reason-code.
  • CASMQ5005S ES MQ Service Process storage allocation error
    The ES MQ Service Process experienced a problem allocating control blocks in local storage.
  • CASMQ5006I mqb-service-message
    The ES MQ Service Process issued a message. The text is mqb-service-message.
  • CASMQ5007I ES MQ Service Process termination started
    The ES MQ Service Process is terminating.
  • CASMQ5008I ES MQ Service Process termination complete
    The ES MQ Service Process has terminated.
  • CASMQ5011I ES MQ Service Process restart in progress
    The IMS TM Control process has been restarted and recovery operations are in progress.
Parent topic: CASMQ Error Messages


CASMQ5001I ES MQ Service Process initialization started<

The server ES MQ Service Process initialization has started.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5001 - CASMQ5011


CASMQ5002S ES MQ Service Process is not running in multi-threaded mode

The ES MQ Service Process has not started with the required underlying thread support.
System Action:
The ES MQ Service Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5001 - CASMQ5011


CASMQ5003I ES MQ Service Process initialization complete

The ES MQ Service Process has completed initialization.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5001 - CASMQ5011


CASMQ5004S ES MQ Service Process registration failed, reason = reason-code

The ES MQ Service Process failed registration. The reason code is reason-code.
System Action:
The ES MQ Service Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5001 - CASMQ5011


CASMQ5005S ES MQ Service Process storage allocation error

The ES MQ Service Process experienced a problem allocating control blocks in local storage.
System Action:
The ES MQ Service Process is terminated.
Resolution:
Notify Micro Focus Support.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5001 - CASMQ5011


CASMQ5006I mqb-service-message

The ES MQ Service Process issued a message. The text is mqb-service-message.
System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5001 - CASMQ5011


CASMQ5007I ES MQ Service Process termination started

The ES MQ Service Process is terminating.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5001 - CASMQ5011


CASMQ5008I ES MQ Service Process termination complete

The ES MQ Service Process has terminated.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5001 - CASMQ5011


CASMQ5011I ES MQ Service Process restart in progress

The IMS TM Control process has been restarted and recovery operations are in progress.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5001 - CASMQ5011


CASMQ5059 - CASMQ5069

  • CASMQ5059I ES MQ process generated a dump to dump dataset dump-dataset
    A dump of the ES MQ process was requested and this dump was generated to the dump-dataset dump dataset.
  • CASMQ5060S ES MQ Service Process failed to load WebSphere MQ support module
    The ES MQ Service Process failed to load the required WebSphere MQ support module.
  • CASMQ5061I ES MQ Listener MQ-Queue for MQ-Queue-Manager requested
    The ES MQ Service Process is starting to listen for messages to initiation queue MQ-Queue on manager MQ-Queue-Manager.
  • CASMQ5062I ES MQ Listener MQ-Queue for MQ-Queue-Manager stopped
    The ES MQ Service Process is starting to listen for messages to initiation queue MQ-Queue on manager MQ-Queue-Manager.
  • CASMQ5063E ES MQ Listener MQ-Queue for MQ-Queue-Manager failed, reason:
    The ES MQ Service Process is starting to listen for messages to initiation queue MQ-Queue on manager MQ-Queue-Manager.
  • CASMQ5064E ES MQ Listener queue-manager-name for queue-name open failed, reason: failure-reason
    The WebSphere MQ trigger monitor task failed to connect to the queue-manager-name queue manager.
  • CASMQ5065E ES MQ Queue Manager security failed, reason:
    The WebSphere MQ trigger monitor task failed to connect to the queue-manager-name queue manager.
  • CASMQ5066E ES MQ Listener queue-manager-name for queue-name initialization failed, reason: failure-reason
    The WebSphere MQ trigger monitor task failed to connect to the queue-manager-name queue manager.
  • CASMQ5067E ES MQ Listener queue-manager-name for queue-name connection lost, reason: failure-reason, retrying...
    The WebSphere MQ trigger monitor task failed to connect to the queue-manager-name queue manager.
  • CASMQ5069I ES MQ Listener MQ-Queue for MQ-Queue-Manager connected
    The ES MQ Service Process is starting to listen for messages to initiation queue MQ-Queue on manager MQ-Queue-Manager.
Parent topic: CASMQ Error Messages


CASMQ5059I ES MQ process generated a dump to dump dataset dump-dataset

A dump of the ES MQ process was requested and this dump was generated to the dump-dataset dump dataset.
System Action:
The ES MQ process produces a dump.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5059 - CASMQ5069


CASMQ5060S ES MQ Service Process failed to load WebSphere MQ support module

The ES MQ Service Process failed to load the required WebSphere MQ support module.
System Action:
The ES MQ Service Process is terminated.
Resolution:
Check the WebSphere MQ installation on the operating system.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5059 - CASMQ5069


CASMQ5061I ES MQ Listener MQ-Queue for MQ-Queue-Manager requested

The ES MQ Service Process is starting to listen for messages to initiation queue MQ-Queue on manager MQ-Queue-Manager.
System Action:
The MQ listener thread is started.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5059 - CASMQ5069


CASMQ5062I ES MQ Listener MQ-Queue for MQ-Queue-Manager stopped

The ES MQ Service Process is starting to listen for messages to initiation queue MQ-Queue on manager MQ-Queue-Manager.
System Action:
The MQ listener thread is started.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5059 - CASMQ5069


CASMQ5063E ES MQ Listener MQ-Queue for MQ-Queue-Manager failed, reason:

The ES MQ Service Process is starting to listen for messages to initiation queue MQ-Queue on manager MQ-Queue-Manager.
System Action:
The MQ listener thread is started.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5059 - CASMQ5069


CASMQ5064E ES MQ Listener queue-manager-name for queue-name open failed, reason: failure-reason

The WebSphere MQ trigger monitor task failed to connect to the queue-manager-name queue manager.
System Action:
Stop WebSphere MQ trigger monitor.
Resolution:
Check the reason code and correct problem if possible then restart the region.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5059 - CASMQ5069


CASMQ5065E ES MQ Queue Manager security failed, reason:

The WebSphere MQ trigger monitor task failed to connect to the queue-manager-name queue manager.
System Action:
Stop WebSphere MQ trigger monitor.
Resolution:
Check the reason code and correct problem if possible then restart the region.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5059 - CASMQ5069


CASMQ5066E ES MQ Listener queue-manager-name for queue-name initialization failed, reason: failure-reason

The WebSphere MQ trigger monitor task failed to connect to the queue-manager-name queue manager.
System Action:
Stop WebSphere MQ trigger monitor.
Resolution:
Check the reason code and correct problem if possible then restart the region.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5059 - CASMQ5069


CASMQ5067E ES MQ Listener queue-manager-name for queue-name connection lost, reason: failure-reason, retrying...

The WebSphere MQ trigger monitor task failed to connect to the queue-manager-name queue manager.
System Action:
Stop WebSphere MQ trigger monitor.
Resolution:
Check the reason code and correct problem if possible then restart the region.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5059 - CASMQ5069


CASMQ5069I ES MQ Listener MQ-Queue for MQ-Queue-Manager connected

The ES MQ Service Process is starting to listen for messages to initiation queue MQ-Queue on manager MQ-Queue-Manager.
System Action:
The MQ listener thread is started.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5059 - CASMQ5069


CASMQ5070 - CASMQ5079

  • CASMQ5070E ES MQ Listener queue-manager-name Queue Manager connect failed, reason: failure-reason
    The WebSphere MQ trigger monitor task failed to connect to the queue-manager-name queue manager.
  • CASMQ5071E ES MQ Service Process query for default Queue Manager name and platform query failed, reason: failure-reason
    The WebSphere MQ trigger monitor task failed when querying MQ for the default queue manager and platform.
  • CASMQ5072E ES MQ Service Process issued a dump command
    The ES MQ Service Process received a dump command and requested the process dump.
  • CASMQ5073I ES MQ Service Process MQSERVER=environment-value
    The ES MQ Service Process client configuration MQSERVER environment variable value is environment-value.
  • CASMQ5074S ES MQ queue queue-name (listener listener-name) application type application-type is unsupported
    The ES MQ Service Process does not support the application-type application type specified in the MQ process definition associated with queue queue-name being accessed by listener listener-name.
  • CASMQ5075W ES MQ trigger message for queue queue-name (listener listener-name) application type application-type is unsupported
    The ES MQ Service Process does not support the application-type application type specified in the MQ trigger message that references queue queue-name. The listener listener-name received this trigger message.
  • CASMQ5076E ES MQ message from queue queue-name (listener listener-name type listener-type) format message-format invalid
    An unexpected message format was received.
  • CASMQ5077I ES MQ default Queue Manager name is default-queue-manager
    An unexpected message format was received.
  • CASMQ5078I ES MQ Listener MQ-Queue for MQ-Queue-Manager reconnected
    The ES MQ Service Process is starting to listen for messages to initiation queue MQ-Queue on manager MQ-Queue-Manager.
  • CASMQ5079I ES MQ Queue Manager default-queue-manager identified
    An unexpected message format was received.
Parent topic: CASMQ Error Messages


CASMQ5070E ES MQ Listener queue-manager-name Queue Manager connect failed, reason: failure-reason

The WebSphere MQ trigger monitor task failed to connect to the queue-manager-name queue manager.
System Action:
Stop WebSphere MQ trigger monitor.
Resolution:
Check the reason code and correct problem if possible then restart the region.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5070 - CASMQ5079


CASMQ5071E ES MQ Service Process query for default Queue Manager name and platform query failed, reason: failure-reason

The WebSphere MQ trigger monitor task failed when querying MQ for the default queue manager and platform.
System Action:
The process will continue but additional failures are likely.
Resolution:
Check the reason code and correct problem if possible then restart the region.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5070 - CASMQ5079


CASMQ5072E ES MQ Service Process issued a dump command

The ES MQ Service Process received a dump command and requested the process dump.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5070 - CASMQ5079


CASMQ5073I ES MQ Service Process MQSERVER=environment-value

The ES MQ Service Process client configuration MQSERVER environment variable value is environment-value.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5070 - CASMQ5079


CASMQ5074S ES MQ queue queue-name (listener listener-name) application type application-type is unsupported

The ES MQ Service Process does not support the application-type application type specified in the MQ process definition associated with queue queue-name being accessed by listener listener-name.
System Action:
The listener is stopped.
Resolution:
Correct the configuration and restart the listener.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5070 - CASMQ5079


CASMQ5075W ES MQ trigger message for queue queue-name (listener listener-name) application type application-type is unsupported

The ES MQ Service Process does not support the application-type application type specified in the MQ trigger message that references queue queue-name. The listener listener-name received this trigger message.
System Action:
The trigger message is moved to the dead-letter queue.
Resolution:
Correct the MQ configuration and retry the request.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5070 - CASMQ5079


CASMQ5076E ES MQ message from queue queue-name (listener listener-name type listener-type) format message-format invalid

An unexpected message format was received.
System Action:
The message is moved to the dead-letter queue.
Resolution:
Check the format and correct problem if possible, then retry the request.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5070 - CASMQ5079


CASMQ5077I ES MQ default Queue Manager name is default-queue-manager

An unexpected message format was received.
System Action:
The message is ignored.
Resolution:
Check the format and correct problem if possible, then retry the request.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5070 - CASMQ5079


CASMQ5078I ES MQ Listener MQ-Queue for MQ-Queue-Manager reconnected

The ES MQ Service Process is starting to listen for messages to initiation queue MQ-Queue on manager MQ-Queue-Manager.
System Action:
The MQ listener thread is started.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5070 - CASMQ5079


CASMQ5079I ES MQ Queue Manager default-queue-manager identified

An unexpected message format was received.
System Action:
The message is ignored.
Resolution:
Check the format and correct problem if possible, then retry the request.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5070 - CASMQ5079


CASMQ5080 - CASMQ5087

  • CASMQ5080I ES MQ Queue Manager authorized
    The named queue manager is currently designated as the default queue manager.
  • CASMQ5081E ES MQ Queue Manager queue-manager-name connection for listener listener-name failed, reason: reason-code
    ES was unable to connect to or identify the named queue manager.
  • CASMQ5082I ES MQ start for Listener MQ-Queue for MQ-Queue-Manager failed - owned by another thread
    The ES MQ Start request targets a listener that has another thread attached.
  • CASMQ5083I ES MQ Listener MQ-Queue% for MQ-Queue-Manager stopped by "CSQ4TRMN:STOP" message
    The ES MQ Service Process has been stopped by an MQ message containing the text "CSQ4TRMN:STOP".
  • CASMQ5084E ES MQ Writer for queue-name (queue manager queue-manager-name) open failed, reason: failure-reason
    The MQ Service Process failed to open the queue-name queue.
  • CASMQ5085E ES MQ Writer writer-name for queue-name failed, reason: failure-reason
    The MQ Service Process failed to write to the queue-name queue.
  • CASMQ5086E ES MQ trigger message for queue queue-name (listener listener-name) application application-id (type application-type) cannot be started
    The ES MQ Service Process cannot start the application-id application of type application-type specified in the MQ trigger message that references queue queue-name. The listener listener-name received this trigger message.
  • CASMQ5087E ES MQ message from queue queue-name (listener listener-name type listener-type) not a valid trigger message
    An invalid trigger message was received.
Parent topic: CASMQ Error Messages


CASMQ5080I ES MQ Queue Manager authorized

The named queue manager is currently designated as the default queue manager.
System Action:
The message is ignored.
Resolution:
Check the format and correct problem if possible, then retry the request.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5080 - CASMQ5087


CASMQ5081E ES MQ Queue Manager queue-manager-name connection for listener listener-name failed, reason: reason-code

ES was unable to connect to or identify the named queue manager.
System Action:
The listener is not started.
Resolution:
Correct the name of the queue manager or make sure it is accessible.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5080 - CASMQ5087


CASMQ5082I ES MQ start for Listener MQ-Queue for MQ-Queue-Manager failed - owned by another thread

The ES MQ Start request targets a listener that has another thread attached.
System Action:
The MQ listener thread is returned to the pool.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5080 - CASMQ5087


CASMQ5083I ES MQ Listener MQ-Queue% for MQ-Queue-Manager stopped by "CSQ4TRMN:STOP" message

The ES MQ Service Process has been stopped by an MQ message containing the text "CSQ4TRMN:STOP".
System Action:
The MQ listener thread is stopped.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5080 - CASMQ5087


CASMQ5084E ES MQ Writer for queue-name (queue manager queue-manager-name) open failed, reason: failure-reason

The MQ Service Process failed to open the queue-name queue.
System Action:
The output message is moved to the dead-letter queue.
Resolution:
Check the reason code and correct problem if possible.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5080 - CASMQ5087


CASMQ5085E ES MQ Writer writer-name for queue-name failed, reason: failure-reason

The MQ Service Process failed to write to the queue-name queue.
System Action:
The output message is moved to the dead-letter queue.
Resolution:
Check the reason code and correct problem if possible.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5080 - CASMQ5087


CASMQ5086E ES MQ trigger message for queue queue-name (listener listener-name) application application-id (type application-type) cannot be started

The ES MQ Service Process cannot start the application-id application of type application-type specified in the MQ trigger message that references queue queue-name. The listener listener-name received this trigger message.
System Action:
The trigger message is moved to the dead-letter queue.
Resolution:
Correct the MQ configuration and retry the request.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5080 - CASMQ5087


CASMQ5087E ES MQ message from queue queue-name (listener listener-name type listener-type) not a valid trigger message

An invalid trigger message was received.
System Action:
The message is moved to the dead-letter queue.
Resolution:
Check the format and correct problem if possible, then retry the request.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5080 - CASMQ5087


CASMS Error Messages

  • CASMS0001W Unexpected key received
    The AID key pressed was not expected by the transaction.
  • CASMS0002W Unexpected PgDn, already at bottom of list
    The page down function key was pressed which was unexpected at this time as the display is already at the bottom of the list.
  • CASMS0003W Unexpected PgUp, already at top of list
    The page up function key was pressed which was unexpected at this time as the display is already at the top of the list.
  • CASMS0004W Invalid selection
    No valid MAP/MAPSETs were selected.
  • CASMS0005W Unsupported function for .MST file
    The function requested is not supported for .MST files.
  • CASMS0006E Unexpected response (EIBRESP=EIBRESP) for function EIBFN=EIBFN
    A CICS API command returned an unexpected response.
  • CASMS0007E Error deleting mapset, RC=return-code
    The 'Delete Mapset' request failed with the return-code specified.
  • CASMS0008W Internal DFHMSD name (DFHMSD-name) does not match mapset (mapset-name)
    The internal name of the mapset (DFHMSD-name) did not match the external .MOD file name. This may occur if the .MOD file is not a valid mapset file or the .MOD file was renamed. The '/m' parameter on dfhpbms can be used to renamed the .MOD file correctly.
  • CASMS0009W Initial mapset cmd-line-mapset not found
    The initial mapset (first argument after the transid) was not found.
  • CASMS0010W Initial map cmd-line-map not found in mapset cmd-line-mapset
    The initial map (second argument after the transid) was not found in the initial mapset.
  • CASMS0011E Internal processing error return-code
    The transaction encountered an internal processing error where return-code means: 1 - Error opening BMS load module 2 - Unrecognized .MST header.
  • CASMS0012I About to delete mapset mapset-name, press <ENTER> to confirm
    A delete request was issued for the mapset named, this message requests confirmation. Press <ENTER> to confirm the delete request, any other AID key to stop the delete.
  • CASMS0013I Delete mapset request canceled
    The delete request was canceled by user request as a key other than <ENTER> was pressed at the confirmation message.
  • CASMS0014I transid transaction complete
    The transaction completed normally.
  • CASMS0015E Unexpected response (EIBRESP) for function EIBFN
    A CICS API command returned an unexpected response.
Parent topic: Enterprise Server Error Messages


CASMS0001W Unexpected key received

The AID key pressed was not expected by the transaction.
System Action:
The system will ignore the key and continue.
Resolution:
Use the correct AID key for the required function or press PF3 to end the transaction.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS Error Messages


CASMS0002W Unexpected PgDn, already at bottom of list

The page down function key was pressed which was unexpected at this time as the display is already at the bottom of the list.
System Action:
The system will ignore the key and continue.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS Error Messages


CASMS0003W Unexpected PgUp, already at top of list

The page up function key was pressed which was unexpected at this time as the display is already at the top of the list.
System Action:
The system will ignore the key and continue.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS Error Messages


CASMS0004W Invalid selection

No valid MAP/MAPSETs were selected.
System Action:
The system will ignore the key and continue.
Resolution:
Either select an option using the '/' key or by positioning the cursor on the desired line and press <ENTER>.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS Error Messages


CASMS0005W Unsupported function for .MST file

The function requested is not supported for .MST files.
System Action:
The system will ignore the key and continue.
Resolution:
Either select a .MOD or reassemble the .BMS source to create a .MOD and retry.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS Error Messages


CASMS0006E Unexpected response (EIBRESP=EIBRESP) for function EIBFN=EIBFN

A CICS API command returned an unexpected response.
System Action:
The transaction will attempt to ignore the error and continue.
Resolution:
Using the EIBFN and EIBRESP codes try to determine the problem based on the function selected, fix and retry.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS Error Messages


CASMS0007E Error deleting mapset, RC=return-code

The 'Delete Mapset' request failed with the return-code specified.
System Action:
The transaction will ignore the error and continue.
Resolution:
Check the return-code from CBL_DELETE_FILE, fix the problem and retry.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS Error Messages


CASMS0008W Internal DFHMSD name (DFHMSD-name) does not match mapset (mapset-name)

The internal name of the mapset (DFHMSD-name) did not match the external .MOD file name. This may occur if the .MOD file is not a valid mapset file or the .MOD file was renamed. The '/m' parameter on dfhpbms can be used to renamed the .MOD file correctly.
System Action:
The transaction will ignore the error and continue.
Resolution:
Check the named mapset file to ensure that it is valid and retry.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS Error Messages


CASMS0009W Initial mapset cmd-line-mapset not found

The initial mapset (first argument after the transid) was not found.
System Action:
The transaction will ignore the error and continue.
Resolution:
If the mapset name was entered incorrectly then choose the mapset from the displayed list. If the desired mapset is not found in the list then ensure that the BMS load module has been assembled correctly and is in a directory on MAPPATH.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS Error Messages


CASMS0010W Initial map cmd-line-map not found in mapset cmd-line-mapset

The initial map (second argument after the transid) was not found in the initial mapset.
System Action:
The transaction will ignore the error and continue.
Resolution:
If the map name was entered incorrectly then choose the map from the displayed list.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS Error Messages


CASMS0011E Internal processing error return-code

The transaction encountered an internal processing error where return-code means: 1 - Error opening BMS load module 2 - Unrecognized .MST header.
System Action:
The transaction will terminate abnormally.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS Error Messages


CASMS0012I About to delete mapset mapset-name, press <ENTER> to confirm

A delete request was issued for the mapset named, this message requests confirmation. Press <ENTER> to confirm the delete request, any other AID key to stop the delete.
System Action:
Wait for AID key.
Resolution:
Press <ENTER> to confirm mapset deletion.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS Error Messages


CASMS0013I Delete mapset request canceled

The delete request was canceled by user request as a key other than <ENTER> was pressed at the confirmation message.
System Action:
Cancel delete request.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS Error Messages


CASMS0014I transid transaction complete

The transaction completed normally.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS Error Messages


CASMS0015E Unexpected response (EIBRESP) for function EIBFN

A CICS API command returned an unexpected response.
System Action:
The transaction will attempt to ignore the error and continue.
Resolution:
Using the EIBFN and EIBRESP codes try to determine the problem based on the function selected, fix and retry.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS Error Messages


CASOP Error Messages

  • CASOP0000I message-part From (user-id,terminal-id,trans-id) message-text
    This is a message from a transaction program using the Write Operator API and not specifying an ACTION level. user-id is the currently signed-on user, if any. terminal-id is the terminal/facility associated with the transaction which sent the message. trans-id is the transaction ID of the transaction which sent the message. message-text is the text of the message. message-part will appear only for messages that exceed a single line and will be of the form 'nn of mm' where nn is the sequence number of this part of the message and mm is the number of parts in the message.
  • CASOP0001W message-part From (user-id,terminal-id,trans-id) message-text
    This is a message from a transaction program using the Write Operator API and specifying ACTION of EVENTUAL. user-id is the currently signed-on user, if any. terminal-id is the terminal/facility associated with the transaction which sent the message. trans-id is the transaction ID of the transaction which sent the message. message-text is the text of the message. message-part will appear only for messages that exceed a single line and will be of the form 'nn of mm' where nn is the sequence number of this part of the message and mm is the number of parts in the message.
  • CASOP0002E message-part From (user-id,terminal-id,trans-id) message-text
    This is a message from a transaction program using the Write Operator API and specifying ACTION of CRITICAL. user-id is the currently signed-on user, if any. terminal-id is the terminal/facility associated with the transaction which sent the message. trans-id is the transaction ID of the transaction which sent the message. message-text is the text of the message. message-part will appear only for messages that exceed a single line and will be of the form 'nn of mm' where nn is the sequence number of this part of the message and mm is the number of parts in the message.
  • CASOP0003S message-part From (user-id,terminal-id,trans-id) message-text
    This is a message from a transaction program using the Write Operator API and specifying ACTION of IMMEDIATE. user-id is the currently signed-on user, if any. terminal-id is the terminal/facility associated with the transaction which sent the message. trans-id is the transaction ID of the transaction which sent the message. message-text is the text of the message. message-part will appear only for messages that exceed a single line and will be of the form 'nn of mm' where nn is the sequence number of this part of the message and mm is the number of parts in the message.
  • CASOP1000W message-part From (user-id,terminal-id) message-text
    This is a message from a user at a terminal using the CWTO supplied transaction. user-id is the currently signed-on user, if any. terminal-id is the terminal/facility associated with the transaction which sent the message. message-text is the text of the message. message-part will appear only for messages that exceed a single line and will be of the form 'nn of mm' where nn is the sequence number of this part of the message and mm is the number of parts in the message.
  • CASOP1900I Message has been sent
    The user message entered via CWTO has been sent to the console.
  • CASOP1901I Enter Message
    There was no text included on the original invocation of the CWTO transaction.
  • CASOP1902W No Input - Reenter
    There was no non-blank text after processing the input screen to CWTO.
  • CASOP1903W CWTO Limitation - Enter Message
    Any text the user included with the original invocation of CWTO has been lost. CWTO must be done from a cleared screen or from one containing only a system message on the last line.
  • CASOP1908S CWTO Terminated by Operator reason
    The user message entered via CWTO has been sent to the console.
  • CASOP1909S CWTO Aborted - Resp=EIBRESP Resp2=EIBRESP2
    The user message entered via CWTO has been sent to the console.
Parent topic: Enterprise Server Error Messages


CASOP0000I message-part From (user-id,terminal-id,trans-id) message-text

This is a message from a transaction program using the Write Operator API and not specifying an ACTION level. user-id is the currently signed-on user, if any. terminal-id is the terminal/facility associated with the transaction which sent the message. trans-id is the transaction ID of the transaction which sent the message. message-text is the text of the message. message-part will appear only for messages that exceed a single line and will be of the form 'nn of mm' where nn is the sequence number of this part of the message and mm is the number of parts in the message.
System Action:
The message is displayed on the system console.
Module:
dfheexin
Destination:
System Console
Parent topic: CASOP Error Messages


CASOP0001W message-part From (user-id,terminal-id,trans-id) message-text

This is a message from a transaction program using the Write Operator API and specifying ACTION of EVENTUAL. user-id is the currently signed-on user, if any. terminal-id is the terminal/facility associated with the transaction which sent the message. trans-id is the transaction ID of the transaction which sent the message. message-text is the text of the message. message-part will appear only for messages that exceed a single line and will be of the form 'nn of mm' where nn is the sequence number of this part of the message and mm is the number of parts in the message.
System Action:
The message is displayed on the system console.
Module:
dfheexin
Destination:
System Console
Parent topic: CASOP Error Messages


CASOP0002E message-part From (user-id,terminal-id,trans-id) message-text

This is a message from a transaction program using the Write Operator API and specifying ACTION of CRITICAL. user-id is the currently signed-on user, if any. terminal-id is the terminal/facility associated with the transaction which sent the message. trans-id is the transaction ID of the transaction which sent the message. message-text is the text of the message. message-part will appear only for messages that exceed a single line and will be of the form 'nn of mm' where nn is the sequence number of this part of the message and mm is the number of parts in the message.
System Action:
The message is displayed on the system console.
Module:
dfheexin
Destination:
System Console
Parent topic: CASOP Error Messages


CASOP0003S message-part From (user-id,terminal-id,trans-id) message-text

This is a message from a transaction program using the Write Operator API and specifying ACTION of IMMEDIATE. user-id is the currently signed-on user, if any. terminal-id is the terminal/facility associated with the transaction which sent the message. trans-id is the transaction ID of the transaction which sent the message. message-text is the text of the message. message-part will appear only for messages that exceed a single line and will be of the form 'nn of mm' where nn is the sequence number of this part of the message and mm is the number of parts in the message.
System Action:
The message is displayed on the system console.
Module:
dfheexin
Destination:
System Console
Parent topic: CASOP Error Messages


CASOP1000W message-part From (user-id,terminal-id) message-text

This is a message from a user at a terminal using the CWTO supplied transaction. user-id is the currently signed-on user, if any. terminal-id is the terminal/facility associated with the transaction which sent the message. message-text is the text of the message. message-part will appear only for messages that exceed a single line and will be of the form 'nn of mm' where nn is the sequence number of this part of the message and mm is the number of parts in the message.
System Action:
The message is displayed on the system console.
Module:
dfhzcwto
Destination:
System Console
Parent topic: CASOP Error Messages


CASOP1900I Message has been sent

The user message entered via CWTO has been sent to the console.
System Action:
The user message will be displayed on the system console.
Module:
dfhzcwto
Destination:
User Terminal
Parent topic: CASOP Error Messages


CASOP1901I Enter Message

There was no text included on the original invocation of the CWTO transaction.
System Action:
Inform user at terminal.
Resolution:
Enter text of message to be sent to console.
Module:
dfhzcwto
Destination:
User Terminal
Parent topic: CASOP Error Messages


CASOP1902W No Input - Reenter

There was no non-blank text after processing the input screen to CWTO.
System Action:
Inform user at terminal.
Resolution:
Enter text of message to be sent to console.
Module:
dfhzcwto
Destination:
User Terminal
Parent topic: CASOP Error Messages


CASOP1903W CWTO Limitation - Enter Message

Any text the user included with the original invocation of CWTO has been lost. CWTO must be done from a cleared screen or from one containing only a system message on the last line.
System Action:
Inform user at terminal.
Resolution:
Enter text of message to be sent to console.
Module:
dfhzcwto
Destination:
User Terminal
Parent topic: CASOP Error Messages


CASOP1908S CWTO Terminated by Operator reason

The user message entered via CWTO has been sent to the console.
System Action:
The CWTO transaction has been terminated and the terminal can continue with another transaction (including CWTO).
Module:
dfhzcwto
Destination:
User Terminal
Parent topic: CASOP Error Messages


CASOP1909S CWTO Aborted - Resp=EIBRESP Resp2=EIBRESP2

The user message entered via CWTO has been sent to the console.
System Action:
The user message will be displayed on the system console.
Module:
dfhzcwto
Destination:
User Terminal
Parent topic: CASOP Error Messages


CASPC Error Messages

  • CASPC0000E Program 'program-id' not found
    An executable for program-id was not found.
  • CASPC0001E Program 'program-id' disabled for transid transid
    A PPT entry exists for program program-id which is currently marked as disabled.
  • CASPC0002E EIBRESP=eibresp invoking program 'program-id'
    An error was encountered when transferring control to the named program. Usually this indicates the program was not found.
  • CASPC0003I CRUN usage: CRUN {program-name}
    No input was supplied with the transaction. Enter a valid program-name following the transaction-id. Only the first eight characters of the program-name are accepted.
  • CASPC0004I COMMAREA passed to CRUN
    A COMMAREA was passed to the supplied transaction CRUN. A program invoked by CRUN may contain a RETURN TRANSID(EIBTRNID) statement that has returned to CRUN instead of the intended program.
Parent topic: Enterprise Server Error Messages


CASPC0000E Program 'program-id' not found

An executable for program-id was not found.
System Action:
The requested transaction is not executed.
Resolution:
Notify the system administrator.
Module:
dfheserv
Destination:
User terminal and TDQ CSMT.
Parent topic: CASPC Error Messages


CASPC0001E Program 'program-id' disabled for transid transid

A PPT entry exists for program program-id which is currently marked as disabled.
System Action:
The requested transaction is not executed.
Resolution:
Notify the system administrator.
Module:
dfheserv
Destination:
User terminal and TDQ CSMT.
Parent topic: CASPC Error Messages


CASPC0002E EIBRESP=eibresp invoking program 'program-id'

An error was encountered when transferring control to the named program. Usually this indicates the program was not found.
System Action:
The requested program is not invoked.
Resolution:
Place an executable version of the program along TRANPATH.
Module:
dfhzcrun
Destination:
User terminal.
Parent topic: CASPC Error Messages


CASPC0003I CRUN usage: CRUN {program-name}

No input was supplied with the transaction. Enter a valid program-name following the transaction-id. Only the first eight characters of the program-name are accepted.
Module:
dfhzcrun
Destination:
User terminal
Parent topic: CASPC Error Messages


CASPC0004I COMMAREA passed to CRUN

A COMMAREA was passed to the supplied transaction CRUN. A program invoked by CRUN may contain a RETURN TRANSID(EIBTRNID) statement that has returned to CRUN instead of the intended program.
Module:
dfhzcrun
Destination:
User terminal
Parent topic: CASPC Error Messages


CASRA Error Messages

  • CASRA0001 - CASRA0019
  • CASRA0020 - CASRA0039
  • CASRA0040 - CASRA0053
  • CASRA0060 - CASRA0082
  • CASRA0101 - CASRA0124
  • CASRA0125 - CASRA0137
  • CASRA1001 - CASRA1019
  • CASRA1020 - CASRA1032
  • CASRA1101 - CASRA1105
  • CASRA1201 - CASRA1218
  • CASRA1301 - CASRA1319
  • CASRA1320 - CASRA1326
  • CASRA1501 - CASRA1515
Parent topic: Enterprise Server Error Messages


CASRA0001 - CASRA0019

  • CASRA0001E Field field-name is invalid
    The field name contained a value that was invalid. Please refer to the field's help for valid values.
  • CASRA0002W Field field-name has been truncated
    The value specified for the field was greater than the capacity of the field in the resource definition data base. The field has been truncated.
  • CASRA0003W Field field-name was specified but is not part of the current record type
    A value was specified for this field but the field is not included in the table currently being processed.
  • CASRA0004W A value was specified for field field-name that is not required
    A value was specified for the field but the field is not required for this particular table entry e.g. a trigger level has been specified for an extra-partition transient data set.
  • CASRA0005E No value specified for required field field-name
    No value was specified for the field but the field is required for this particular table entry e.g. a Terminal id for the terminal table.
  • CASRA0006E field-name must not start with the characters 'DFH'
    A Group or resource name must not start with the characters DFH.
  • CASRA0007E Either a program ID or a remote system ID must be specified
    Only one of fields program ID or remote system ID can be specified not both for a PCT entry.
  • CASRA0008E Remote trans ID specified but no remote system ID
    If a remote trans ID is specified for a PCT entry then a remote system ID must also be specified.
  • CASRA0009E Remote Trans ID specified but no remote system ID
    If a remote transaction ID is specified for a PPT entry then a remote system ID must also be specified.
  • CASRA0010E Remote program ID specified but no remote system ID
    If a remote program name is specified for a PPT entry then a remote system ID must also be specified.
  • CASRA0011E Minimum record length not required when remote sysid specified
    The minimum record length is not required for a remote file.
  • CASRA0012E Maximum record length not required when remote sysid specified
    The maximum record length is not required for a remote file.
  • CASRA0013E Remote file name specified but no remote system id
    If a remote file name is specified then a remote system ID must also be specified.
  • CASRA0014E Key position specified when split keys active
    The split key position fields must be used to specify the key positions when using split keys not the global position field.
  • CASRA0015E Key length specified when split keys active
    The split key length fields must be used to specify the key lengths when using split keys not the global length field.
  • CASRA0016E Minimum record length greater than the maximum record length
    The minimum record length must be less than or equal to the maximum record length.
  • CASRA0017E Key position not within the minimum record length
    The key must be contained in the minimum record size.
  • CASRA0018E Key not contained in the minimum record size
    The key position plus the key length exceed the minimum record size.
  • CASRA0019E Either a remote system ID or a file share server can be specified
    Either a remote system ID or a file share server name can be specified but not both.
Parent topic: CASRA Error Messages


CASRA0001E Field field-name is invalid

The field name contained a value that was invalid. Please refer to the field's help for valid values.
Resolution:
Correct the field in error.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0002W Field field-name has been truncated

The value specified for the field was greater than the capacity of the field in the resource definition data base. The field has been truncated.
System Action:
If write with warnings set the truncated value is written.
Resolution:
If write with warnings not set then specify a shorter field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0003W Field field-name was specified but is not part of the current record type

A value was specified for this field but the field is not included in the table currently being processed.
System Action:
The value is ignored.
Resolution:
Correct the calling program to pass only those fields required.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0004W A value was specified for field field-name that is not required

A value was specified for the field but the field is not required for this particular table entry e.g. a trigger level has been specified for an extra-partition transient data set.
System Action:
The value is ignored.
Resolution:
Correct the calling program to pass only those fields required.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0005E No value specified for required field field-name

No value was specified for the field but the field is required for this particular table entry e.g. a Terminal id for the terminal table.
Resolution:
Specify a value for the required field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0006E field-name must not start with the characters 'DFH'

A Group or resource name must not start with the characters DFH.
Resolution:
Specify a new resource or Group name.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0007E Either a program ID or a remote system ID must be specified

Only one of fields program ID or remote system ID can be specified not both for a PCT entry.
Resolution:
Delete the unwanted field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0008E Remote trans ID specified but no remote system ID

If a remote trans ID is specified for a PCT entry then a remote system ID must also be specified.
Resolution:
Specify the remote system id.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0009E Remote Trans ID specified but no remote system ID

If a remote transaction ID is specified for a PPT entry then a remote system ID must also be specified.
Resolution:
Specify the remote system id.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0010E Remote program ID specified but no remote system ID

If a remote program name is specified for a PPT entry then a remote system ID must also be specified.
Resolution:
Specify the remote system id.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0011E Minimum record length not required when remote sysid specified

The minimum record length is not required for a remote file.
Resolution:
Specify the minimum record length as zero.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0012E Maximum record length not required when remote sysid specified

The maximum record length is not required for a remote file.
Resolution:
Specify the maximum record length as zero.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0013E Remote file name specified but no remote system id

If a remote file name is specified then a remote system ID must also be specified.
Resolution:
Specify the remote system id.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0014E Key position specified when split keys active

The split key position fields must be used to specify the key positions when using split keys not the global position field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0015E Key length specified when split keys active

The split key length fields must be used to specify the key lengths when using split keys not the global length field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0016E Minimum record length greater than the maximum record length

The minimum record length must be less than or equal to the maximum record length.
Resolution:
Correct the minimum record length.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0017E Key position not within the minimum record length

The key must be contained in the minimum record size.
Resolution:
Correct the key position value.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0018E Key not contained in the minimum record size

The key position plus the key length exceed the minimum record size.
Resolution:
Correct either the key length or the key position.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0019E Either a remote system ID or a file share server can be specified

Either a remote system ID or a file share server name can be specified but not both.
Resolution:
Delete either the remote system ID or the file share server name.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0001 - CASRA0019


CASRA0020 - CASRA0039

  • CASRA0020E Remote System ID must not be specified if a file path present
    The remote system ID field is not required if a file path is specified.
  • CASRA0021E Remote System ID not required if a file name override specified
    The file name override field is not required if a remote system ID is present.
  • CASRA0022E Remote System ID not required if a file extension is specified
    The file extension field is not required if a remote system ID is present.
  • CASRA0023E File format is fixed but the min and max rec lengths are not equal
    If the file format is specified as fixed then the minimum and maximum record lengths must be equal.
  • CASRA0024E Split key flag set to yes but no split keys defined
    The split key flag has been set to yes but no split key length and positions have been specified.
  • CASRA0025E Duplicate keys not allowed when file type set to KSDS
    The duplicate key flag must be set to no when the file type is KSDS.
  • CASRA0026E Terminal specified when the Queue type is not intra-partition
    A terminal can only be associated with an intra-partition transient data queue.
  • CASRA0027E Transaction specified when the Queue type is not intra-partition
    A transaction can only be associated with an intra-partition transient data queue.
  • CASRA0028E Indirect name specified when Queue type is not indirect
    An indirect destination can only be specified for an indirect transient data queue.
  • CASRA0029E Trigger level specified for an indirect or extra-partition queue
    A trigger level can only be specified for an intrapartition transient data queue.
  • CASRA0030E Maximum record length specified for indirect or intra-partition queue
    Maximum record length is only required with an extrapartition transient data queue.
  • CASRA0031E Minimum record length specified for indirect or intra-partition queue
    Minimum record length is only required with an extrapartition transient data queue.
  • CASRA0032E Minimum record length greater than the maximum record length
    The maximum record length must be equal to or greater than the minimum record length.
  • CASRA0033E File name specified for an indirect or intra-partition queue
    A file name can only be specified for an extra-partition transient data queue.
  • CASRA0034E File path specified for an indirect or intra-partition queue
    A file path can only be specified for an extra-partition transient data queue.
  • CASRA0035E File extension specified for an indirect or intra-partition queue
    A file extension can only be specified for an extra-partition transient data queue.
  • CASRA0036E Storage cushion exceeds half the shared pages value.
    Less than half the number shared pages should be allocated to the storage cushion.
  • CASRA0037E Remote data ID specified but no remote system ID specified
    If a remote data ID is specified then a remote system ID must be specified.
  • CASRA0038E No extended data stream specified but highlight or color specified
    If highlight and/or color are specified the extended data stream flag must be set to yes.
  • CASRA0039E Remote system ID specified but no remote terminal ID specified
    If a remote system ID is specified then a remote terminal ID must be specified.
Parent topic: CASRA Error Messages


CASRA0020E Remote System ID must not be specified if a file path present

The remote system ID field is not required if a file path is specified.
Resolution:
Delete either the remote system ID of the file path.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0021E Remote System ID not required if a file name override specified

The file name override field is not required if a remote system ID is present.
Resolution:
Delete either the file name override or the remote system id.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0022E Remote System ID not required if a file extension is specified

The file extension field is not required if a remote system ID is present.
Resolution:
Delete either the file extension or the remote system id.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0023E File format is fixed but the min and max rec lengths are not equal

If the file format is specified as fixed then the minimum and maximum record lengths must be equal.
Resolution:
Correct either the record lengths or the file format.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0024E Split key flag set to yes but no split keys defined

The split key flag has been set to yes but no split key length and positions have been specified.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0025E Duplicate keys not allowed when file type set to KSDS

The duplicate key flag must be set to no when the file type is KSDS.
Resolution:
Correct either the file type or the duplicate flag.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0026E Terminal specified when the Queue type is not intra-partition

A terminal can only be associated with an intra-partition transient data queue.
Resolution:
Correct the queue type or delete the terminal id.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0027E Transaction specified when the Queue type is not intra-partition

A transaction can only be associated with an intra-partition transient data queue.
Resolution:
Correct the queue type or delete the transaction id.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0028E Indirect name specified when Queue type is not indirect

An indirect destination can only be specified for an indirect transient data queue.
Resolution:
Correct the queue type or delete the indirect destination.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0029E Trigger level specified for an indirect or extra-partition queue

A trigger level can only be specified for an intrapartition transient data queue.
Resolution:
Correct the queue type or delete the trigger level.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0030E Maximum record length specified for indirect or intra-partition queue

Maximum record length is only required with an extrapartition transient data queue.
Resolution:
Correct the queue type or delete the maximum record length.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0031E Minimum record length specified for indirect or intra-partition queue

Minimum record length is only required with an extrapartition transient data queue.
Resolution:
Correct the queue type or delete the minimum record length.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0032E Minimum record length greater than the maximum record length

The maximum record length must be equal to or greater than the minimum record length.
Resolution:
Correct either the minimum or maximum record length.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0033E File name specified for an indirect or intra-partition queue

A file name can only be specified for an extra-partition transient data queue.
Resolution:
Correct the queue type or delete the file name.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0034E File path specified for an indirect or intra-partition queue

A file path can only be specified for an extra-partition transient data queue.
Resolution:
Correct the queue type or delete the file path.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0035E File extension specified for an indirect or intra-partition queue

A file extension can only be specified for an extra-partition transient data queue.
Resolution:
Correct the queue type or delete the file extension.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0036E Storage cushion exceeds half the shared pages value.

Less than half the number shared pages should be allocated to the storage cushion.
Resolution:
Correct either the shared pages or storage cushion value.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0037E Remote data ID specified but no remote system ID specified

If a remote data ID is specified then a remote system ID must be specified.
Resolution:
Specify a remote system ID or delete the remote data id.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0038E No extended data stream specified but highlight or color specified

If highlight and/or color are specified the extended data stream flag must be set to yes.
Resolution:
Either set extended DS to Yes or set highlight and color to No.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0039E Remote system ID specified but no remote terminal ID specified

If a remote system ID is specified then a remote terminal ID must be specified.
Resolution:
Specify a remote terminal ID or delete the remote system id.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0020 - CASRA0039


CASRA0040 - CASRA0053

  • CASRA0040E Remote terminal ID specified but no remote system ID specified
    If a remote terminalid is specified then a remote system ID must be specified.
  • CASRA0041E Minimum record length greater than the maximum record length
    The maximum record length must be equal to or greater than the minimum record length.
  • CASRA0042E More than one database has been defined
    Only one database (other than IMS) may be defined.
  • CASRA0043E No indirect name specified when Queue type is indirect
    An indirect destination must be specified for an indirect transient data queue.
  • CASRA0044E Universal Client specified, but session count is 0
    Universal Client has been specified without a correct number of sessions.
  • CASRA0045E Both MFNODE and MFPORT must be entered
    When specifying a CCI connection using MFNODE, the port number (MFPORT) must also be specified.
  • CASRA0046E PROTOCOL(HTTP|USER) and AUTH(ASSERTED) meaningless
    The value ASSERTED for AUTHENTICATE is meaningless when the PROTOCOL is HTTP or USER.
  • CASRA0047E PROTOCOL(ECI|IPIC) and AUTHENTICATE meaningless
    Any value for AUTHENTICATE is meaningless when the PROTOCOL is ECI or IPIC.
  • CASRA0048E PROTOCOL(IIOP) and AUTH(BASIC|AUTOREGISTER|AUTOMATIC) meaningless
    The values BASIC, AUTOREGISTER and AUTOMATIC for AUTHENTICATE are meaningless when the PROTOCOL is IIOP.
  • CASRA0049E ATTACHSEC must be blank for PROTOCOL(HTTP|USER|IIOP)
    ATTACHSEC may be specified only when you specify PROTOCOL ECI or IPIC.
  • CASRA0050E ALT file type requires base file name
    A base file name must be specified for an FCT of type ALT.
  • CASRA0051E Base file name only required for an FCT of type ALT
    A base file name need only be specified for an FCT of type ALT.
  • CASRA0052E Remote parameters specified for FCT of type ALT
    An FCT of type ALT cannot specify a remote system.
  • CASRA0053E Transaction ID contains invalid characters
    Transaction ID contains invalid characters.
Parent topic: CASRA Error Messages


CASRA0040E Remote terminal ID specified but no remote system ID specified

If a remote terminalid is specified then a remote system ID must be specified.
Resolution:
Specify a remote system ID or delete the remote terminal id.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0040 - CASRA0053


CASRA0041E Minimum record length greater than the maximum record length

The maximum record length must be equal to or greater than the minimum record length.
Resolution:
Correct either the minimum or maximum record length.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0040 - CASRA0053


CASRA0042E More than one database has been defined

Only one database (other than IMS) may be defined.
Resolution:
Correct the list of databases such that only one is defined.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0040 - CASRA0053


CASRA0043E No indirect name specified when Queue type is indirect

An indirect destination must be specified for an indirect transient data queue.
Resolution:
Correct the queue type or add the indirect destination.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0040 - CASRA0053


CASRA0044E Universal Client specified, but session count is 0

Universal Client has been specified without a correct number of sessions.
Resolution:
Correct the number of sessions.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0040 - CASRA0053


CASRA0045E Both MFNODE and MFPORT must be entered

When specifying a CCI connection using MFNODE, the port number (MFPORT) must also be specified.
Resolution:
Correct the node and port number.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0040 - CASRA0053


CASRA0046E PROTOCOL(HTTP|USER) and AUTH(ASSERTED) meaningless

The value ASSERTED for AUTHENTICATE is meaningless when the PROTOCOL is HTTP or USER.
Resolution:
Correct the AUTHENTICATE field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0040 - CASRA0053


CASRA0047E PROTOCOL(ECI|IPIC) and AUTHENTICATE meaningless

Any value for AUTHENTICATE is meaningless when the PROTOCOL is ECI or IPIC.
Resolution:
Correct the AUTHENTICATE field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0040 - CASRA0053


CASRA0048E PROTOCOL(IIOP) and AUTH(BASIC|AUTOREGISTER|AUTOMATIC) meaningless

The values BASIC, AUTOREGISTER and AUTOMATIC for AUTHENTICATE are meaningless when the PROTOCOL is IIOP.
Resolution:
Correct the AUTHENTICATE field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0040 - CASRA0053


CASRA0049E ATTACHSEC must be blank for PROTOCOL(HTTP|USER|IIOP)

ATTACHSEC may be specified only when you specify PROTOCOL ECI or IPIC.
Resolution:
Correct the ATTACHSEC field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0040 - CASRA0053


CASRA0050E ALT file type requires base file name

A base file name must be specified for an FCT of type ALT.
Resolution:
Provide a base file name.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0040 - CASRA0053


CASRA0051E Base file name only required for an FCT of type ALT

A base file name need only be specified for an FCT of type ALT.
Resolution:
Change FCT to ALT or do not provide a base file name.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0040 - CASRA0053


CASRA0052E Remote parameters specified for FCT of type ALT

An FCT of type ALT cannot specify a remote system.
Resolution:
Change FCT type or do not specify remote parameters.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0040 - CASRA0053


CASRA0053E Transaction ID contains invalid characters

Transaction ID contains invalid characters.
Resolution:
Change Transaction ID to contain characters A-Z a-z 0-9 $ @ # . / - _ % & ¢ ? ! : | " = ¬ , ; < >.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0040 - CASRA0053


CASRA0060 - CASRA0082

  • CASRA0060E (subst$) value is invalid
    The string value supplied is invalid transient data queue.
  • CASRA0061E (subst$) value is out of range
    The numeric value supplied is outside the valid range.
  • CASRA0062E (subst$) value has incorrect length
    The string value supplied is not of the correct length.
  • CASRA0063S Unrecognised field identifier
    The field identifier passed into the function was not recognised.
  • CASRA0064E System resource - read access only
    The resource is owned by the system modification not allowed.
  • CASRA0065I No more resources of this type in the group
    There are no more resources of this type in the specified group.
  • CASRA0066E Resource entry has been changed by external process
    The resource has been modified by another process since last read.
  • CASRA0070E The maximum number of groups in a list has been reached
    The maximum number of groups in a list has been reached.
  • CASRA0071I The list does not contain any groups
    The list does not contain any groups.
  • CASRA0072I No more groups in the list
    No more groups in the list.
  • CASRA0073E The specified group is not a member of the list
    The specified group is not a member of the list.
  • CASRA0074E Remote system ID must be supplied for files of type 'Undefined'
    The specified group is not a member of the list.
  • CASRA0075W Specified dataset name is not cataloged
    The use catalog flag has been set but the specified DSN is not defined to the catalog.
  • CASRA0076E Remote system ID must not be supplied for cataloged files
    A cataloged file cannot be remote.
  • CASRA0077W The attributes previously specified do not match those defined in the catalog
    The attributes (record lengths, key information) are different from those specified in the catalog.
  • CASRA0078E The catalog entry is a non-VSAM file
    The selected catalog entry is not a VSAM file.
  • CASRA0079E SYNCLEVEL WRONG
    SYNCLEVEL.
  • CASRA0080E The length of GROUP name is too long, must be <= 8 characters
    The length of the GROUP name is too long, it must be less than or equal to eight characters.
  • CASRA0081E The length of The attribute at fault e.g. program name. is too long
    The length of the attribute is too long.
  • CASRA0082E The length of The attribute at fault e.g. port number. cannot be zero
    The length of the attribute is zero, but it cannot be.
Parent topic: CASRA Error Messages


CASRA0060E (subst$) value is invalid

The string value supplied is invalid transient data queue.
Resolution:
Supply a valid string for this field.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0061E (subst$) value is out of range

The numeric value supplied is outside the valid range.
Resolution:
Supply a value that is within the valid range for this field.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0062E (subst$) value has incorrect length

The string value supplied is not of the correct length.
Resolution:
Supply a string with a valid length for this field.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0063S Unrecognised field identifier

The field identifier passed into the function was not recognised.
Resolution:
Pass a valid field identifier on the function call.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0064E System resource - read access only

The resource is owned by the system modification not allowed.
Resolution:
Do not attempt to update this resource.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0065I No more resources of this type in the group

There are no more resources of this type in the specified group.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0066E Resource entry has been changed by external process

The resource has been modified by another process since last read.
Resolution:
Reread record to refresh details.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0070E The maximum number of groups in a list has been reached

The maximum number of groups in a list has been reached.
Resolution:
Do not attempt to add to the list.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0071I The list does not contain any groups

The list does not contain any groups.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0072I No more groups in the list

No more groups in the list.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0073E The specified group is not a member of the list

The specified group is not a member of the list.
Resolution:
Specify a different group.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0074E Remote system ID must be supplied for files of type 'Undefined'

The specified group is not a member of the list.
Resolution:
Specify a different group.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0075W Specified dataset name is not cataloged

The use catalog flag has been set but the specified DSN is not defined to the catalog.
Resolution:
Define catalog entry prior to running a CICS region.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0076E Remote system ID must not be supplied for cataloged files

A cataloged file cannot be remote.
Resolution:
Do not specify remote system ID.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0077W The attributes previously specified do not match those defined in the catalog

The attributes (record lengths, key information) are different from those specified in the catalog.
Resolution:
Check that the correct dataset has been specified.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0078E The catalog entry is a non-VSAM file

The selected catalog entry is not a VSAM file.
Resolution:
Specify a VSAM catalog entry.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0079E SYNCLEVEL WRONG

SYNCLEVEL.
Resolution:
SYNCLEVEL.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0080E The length of GROUP name is too long, must be <= 8 characters

The length of the GROUP name is too long, it must be less than or equal to eight characters.
Resolution:
Reduce the size of the group name.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0081E The length of The attribute at fault e.g. program name. is too long

The length of the attribute is too long.
Resolution:
Reduce the size of the attribute.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0082E The length of The attribute at fault e.g. port number. cannot be zero

The length of the attribute is zero, but it cannot be.
Resolution:
Add some data to the attribute or remove the attribute completely so the default value is used.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0082


CASRA0101 - CASRA0124

  • CASRA0101E URM must be blank for PROTOCOL(IIOP) and AUTH(ASSERTED|CERTIFICATE)
    URM may not be specified when you specify PROTOCOL(IIOP) and AUTH(ASSERTED|CERTIFICATE).
  • CASRA0102E SSL must specify CLIENTAUTH for AUTH(AUTOREGISTER|CERTIFICATE)
    SSL must specify CLIENTAUTH when you specify AUTH(AUTOREGISTER|CERTIFICATE).
  • CASRA0103E SOCKETCLOSE must specify NO for PROTOCOL(ECI|IPIC)
    SOCKETCLOSE must specify NO when you specify PROTOCOL(ECI|IPIC) .
  • CASRA0104E CONVERTER cannot be used with HFS File
    CONVERTER and HFS file are mutually exclusive.
  • CASRA0105E PROGRAM cannot be used with HFS File
    PROGRAM and HFS file are mutually exclusive.
  • CASRA0106E TRANSACTION cannot be used with HFS File
    TRANSACTION and HFS file are mutually exclusive.
  • CASRA0107E MEDIATYPE must be specified when using HFS File
    MEDIATYPE was not specified but HFS File was used.
  • CASRA0108E Invalid MEDIATYPE specified
    The MEDIATYPE entered does not conform with the IANA standard defined at http://www.iana.org/assignments/media-types/.
  • CASRA0109E Invalid HOST specified
    The values entered in the HOST field can only be alphanumeric characters, hyphens (-) or periods (.) Or a * in first position.
  • CASRA0110E Invalid values in APPENDCRLF field
    The values entered in the APPENDCRLF field can only be YES or NO.
  • CASRA0111E Invalid values in FILE field
    The values entered in the FILE field are incorrect. Accepted values: A-Z 0-9 $ @ #.
  • CASRA0112E Invalid values in HFSFILE field
    The values entered in the HFSFILE field are incorrect. Accepted values: A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ¬ , ; < >.
  • CASRA0113E Invalid values in TSQUEUE field
    The values entered in the TSQUEUE field are incorrect. Accepted values: A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ¬ , ; < >.
  • CASRA0114E Invalid values in TDQUEUE field
    The values entered in the TDQUEUE field are incorrect. Accepted values: A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ¬ , ; < >.
  • CASRA0115E Invalid values in PROGRAM field
    The values entered in the PROGRAM field are incorrect. Accepted values: A-Z 0-9 $ @ #.
  • CASRA0116E Invalid values in EXITPRG field
    The values entered in the EXITPRG field are incorrect. Accepted values: A-Z 0-9 $ @ #.
  • CASRA0117E Invalid values in DDNAME field
    The values entered in the DDNAME field are incorrect. Accepted values: A-Z 0-9 $ @ #.
  • CASRA0118E Invalid values in MEMBERNAME field
    The values entered in the MEMBERNAME field are incorrect. Accepted values: A-Z 0-9 $ @ #.
  • CASRA0119E Invalid values in TYPE field
    The values entered in the TYPE field can only be (EBCDIC|ASCII|BINARY).
  • CASRA0120E Invalid values in TEMPLATENAME field
    The values entered in the TEMPLATENAME field are incorrect. Accepted values: A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ¬ , ; < >.
  • CASRA0121E Invalid values in DOCTEMPLATE field
    The values entered in the DOCTEMPLATE field are incorrect. Accepted values: A-Z 0-9 $ @ #.
  • CASRA0122E FILE|TSQUEUE|TDQUEUE|PROGRAM|EXITPGM|HFSFILE OR MEMBERNAME must be specified
    All the option fields are empty.
  • CASRA0123E Option conflicts with other option and is ignored
    The specified option conflicts with an other one.
  • CASRA0124E Option conflicts with other option and is ignored
    The specified option conflicts with another one.
Parent topic: CASRA Error Messages


CASRA0101E URM must be blank for PROTOCOL(IIOP) and AUTH(ASSERTED|CERTIFICATE)

URM may not be specified when you specify PROTOCOL(IIOP) and AUTH(ASSERTED|CERTIFICATE).
Resolution:
Correct the URM field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0102E SSL must specify CLIENTAUTH for AUTH(AUTOREGISTER|CERTIFICATE)

SSL must specify CLIENTAUTH when you specify AUTH(AUTOREGISTER|CERTIFICATE).
Resolution:
Correct the SSL field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0103E SOCKETCLOSE must specify NO for PROTOCOL(ECI|IPIC)

SOCKETCLOSE must specify NO when you specify PROTOCOL(ECI|IPIC) .
Resolution:
Correct the SOCKETCLOSE field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0104E CONVERTER cannot be used with HFS File

CONVERTER and HFS file are mutually exclusive.
Resolution:
Remove either the CONVERTER field or the HFS file field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0105E PROGRAM cannot be used with HFS File

PROGRAM and HFS file are mutually exclusive.
Resolution:
Remove either the PROGRAM field or the HFS file field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0106E TRANSACTION cannot be used with HFS File

TRANSACTION and HFS file are mutually exclusive.
Resolution:
Remove either the TRANSACTION field or the HFS file field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0107E MEDIATYPE must be specified when using HFS File

MEDIATYPE was not specified but HFS File was used.
Resolution:
Add a MEDIATYPE field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0108E Invalid MEDIATYPE specified

The MEDIATYPE entered does not conform with the IANA standard defined at http://www.iana.org/assignments/media-types/.
Resolution:
Correct the MEDIATYPE field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0109E Invalid HOST specified

The values entered in the HOST field can only be alphanumeric characters, hyphens (-) or periods (.) Or a * in first position.
Resolution:
Correct the HOST field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0110E Invalid values in APPENDCRLF field

The values entered in the APPENDCRLF field can only be YES or NO.
Resolution:
Correct the APPENDCRLF field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0111E Invalid values in FILE field

The values entered in the FILE field are incorrect. Accepted values: A-Z 0-9 $ @ #.
Resolution:
Correct the FILE field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0112E Invalid values in HFSFILE field

The values entered in the HFSFILE field are incorrect. Accepted values: A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ¬ , ; < >.
Resolution:
Correct the HFSFILE field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0113E Invalid values in TSQUEUE field

The values entered in the TSQUEUE field are incorrect. Accepted values: A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ¬ , ; < >.
Resolution:
Correct the TSQUEUE field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0114E Invalid values in TDQUEUE field

The values entered in the TDQUEUE field are incorrect. Accepted values: A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ¬ , ; < >.
Resolution:
Correct the TDQUEUE field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0115E Invalid values in PROGRAM field

The values entered in the PROGRAM field are incorrect. Accepted values: A-Z 0-9 $ @ #.
Resolution:
Correct the PROGRAM field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0116E Invalid values in EXITPRG field

The values entered in the EXITPRG field are incorrect. Accepted values: A-Z 0-9 $ @ #.
Resolution:
Correct the EXITPRG field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0117E Invalid values in DDNAME field

The values entered in the DDNAME field are incorrect. Accepted values: A-Z 0-9 $ @ #.
Resolution:
Correct the DDNAME field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0118E Invalid values in MEMBERNAME field

The values entered in the MEMBERNAME field are incorrect. Accepted values: A-Z 0-9 $ @ #.
Resolution:
Correct the MEMBERNAME field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0119E Invalid values in TYPE field

The values entered in the TYPE field can only be (EBCDIC|ASCII|BINARY).
Resolution:
Correct the TYPE field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0120E Invalid values in TEMPLATENAME field

The values entered in the TEMPLATENAME field are incorrect. Accepted values: A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ¬ , ; < >.
Resolution:
Correct the TEMPLATENAME field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0121E Invalid values in DOCTEMPLATE field

The values entered in the DOCTEMPLATE field are incorrect. Accepted values: A-Z 0-9 $ @ #.
Resolution:
Correct the DOCTEMPLATE field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0122E FILE|TSQUEUE|TDQUEUE|PROGRAM|EXITPGM|HFSFILE OR MEMBERNAME must be specified

All the option fields are empty.
Resolution:
Enter at least one of the option fields.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0123E Option conflicts with other option and is ignored

The specified option conflicts with an other one.
Resolution:
Check the options used, and correct it.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0124E Option conflicts with other option and is ignored

The specified option conflicts with another one.
Resolution:
Check the options used, and correct it.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0101 - CASRA0124


CASRA0125 - CASRA0137

  • CASRA0125E Invalid values in TYPE field
    The values entered in the TYPE field are incorrect. Accepted values: INITIATOR|PRINTER|IMSMPR.
  • CASRA0126E Invalid values in NAME field
    The values entered in the NAME field are incorrect. Accepted values: not blank.
  • CASRA0127E Invalid values in CLASS field
    The values entered in the CLASS field are incorrect. Accepted values: A-Z 0-9 for INITIATOR/PRINTER and 0-9 for IMSMPR.
  • CASRA0128W Port number The well-known port number. implies protocol The new protocol the TCPIPSERVICE has been set to use., so protocol has been changed to The new protocol the TCPIPSERVICE has been set to use.
    A well-known port number has been specified with a mismatching protocol e.g. port 80 with protocol ECI.
  • CASRA0129W Port number The well-known port number. implies that SSL be switched to NO, so SSL has been switched to NO
    A well-known non-secure port number has been specified with SSL set to YES or CLIENTAUTH e.g. port 80 with SSL set to YES.
  • CASRA0130W Port number The well-known port number. implies that SSL be switched to YES, so SSL has been switched to YES
    A well-known secure port number has been specified with SSL set to NO e.g. port 443 with SSL set to NO.
  • CASRA0131W Protocol The protocol the TCPIPSERVICE has been set to use. implies transaction The new transaction the TCPIPSERVICE has been set to use., so transaction has been set to The new transaction the TCPIPSERVICE has been set to use.
    A pre-defined transaction for another protocol has been specified e.g. CWXN should only be used for the HTTP protocol or the transaction field is empty.
  • CASRA0132E For protocol The protocol the TCPIPSERVICE has been set to use. option The attribute and value that is meaningless. is meaningless
    Certain protocols do not require specific attributes e.g. protocol ECI does not recognise the URM attribute.
  • CASRA0133S Use of protocol The protocol the TCPIPSERVICE has been set to use. implies The attribute and value that is required. option must be specified
    Certain protocols require specific attributes and values e.g. protocol ECI requires SOCKETCLOSE to be set to NO.
  • CASRA0134S Use of The attribute and value specified. option implies The attribute and value that is required. option must be specified
    Certain attributes require other attributes and values e.g. AUTHENTICATE(CERTIFICATE) requires SSL to be set to CLIENTAUTH.
  • CASRA0135W Protocol The protocol the TCPIPSERVICE has been set to use. implies URM. The default value has been assumed
    The URM field is empty, so the default URM is specified.
  • CASRA0136W Transaction The new transaction the TCPIPSERVICE has been set to use. implies protocol The protocol the TCPIPSERVICE has been set to use., so protocol has been set to The protocol the TCPIPSERVICE has been set to use.
    A pre-defined transaction has been specified with no protocol, so the protocol is set.#.
  • CASRA0137E The new transaction the TCPIPSERVICE has been set to use. option conflicts with The protocol the TCPIPSERVICE has been set to use. option and is ignored
    A pre-defined transaction has been specified with no protocol, so the protocol is set.
Parent topic: CASRA Error Messages


CASRA0125E Invalid values in TYPE field

The values entered in the TYPE field are incorrect. Accepted values: INITIATOR|PRINTER|IMSMPR.
Resolution:
Correct the TYPE field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0125 - CASRA0137


CASRA0126E Invalid values in NAME field

The values entered in the NAME field are incorrect. Accepted values: not blank.
Resolution:
Correct the NAME field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0125 - CASRA0137


CASRA0127E Invalid values in CLASS field

The values entered in the CLASS field are incorrect. Accepted values: A-Z 0-9 for INITIATOR/PRINTER and 0-9 for IMSMPR.
Resolution:
Correct the CLASS field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0125 - CASRA0137


CASRA0128W Port number The well-known port number. implies protocol The new protocol the TCPIPSERVICE has been set to use., so protocol has been changed to The new protocol the TCPIPSERVICE has been set to use.

A well-known port number has been specified with a mismatching protocol e.g. port 80 with protocol ECI.
Resolution:
If the specified protocol is required, then specify a port that is not in the range of well-known ports.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0125 - CASRA0137


CASRA0129W Port number The well-known port number. implies that SSL be switched to NO, so SSL has been switched to NO

A well-known non-secure port number has been specified with SSL set to YES or CLIENTAUTH e.g. port 80 with SSL set to YES.
Resolution:
If SSL is required, then specify the well-known secure port for that protocol e.g. 443 for HTTP, or specify a port in the ephemeral range.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0125 - CASRA0137


CASRA0130W Port number The well-known port number. implies that SSL be switched to YES, so SSL has been switched to YES

A well-known secure port number has been specified with SSL set to NO e.g. port 443 with SSL set to NO.
Resolution:
If SSL is not required, then specify the well-known non-secure port for that protocol e.g. 80 for HTTP, or specify a port in the ephemeral range.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0125 - CASRA0137


CASRA0131W Protocol The protocol the TCPIPSERVICE has been set to use. implies transaction The new transaction the TCPIPSERVICE has been set to use., so transaction has been set to The new transaction the TCPIPSERVICE has been set to use.

A pre-defined transaction for another protocol has been specified e.g. CWXN should only be used for the HTTP protocol or the transaction field is empty.
Resolution:
Specify a transaction whose name does not clash with any of the pre-defined transaction names: CWXN, CIEP, CIRR, CISS or CWXU; or use the correct pre-defined transaction for the specified protocol.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0125 - CASRA0137


CASRA0132E For protocol The protocol the TCPIPSERVICE has been set to use. option The attribute and value that is meaningless. is meaningless

Certain protocols do not require specific attributes e.g. protocol ECI does not recognise the URM attribute.
Resolution:
Remove the meaningless options to stop this message from being returned.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0125 - CASRA0137


CASRA0133S Use of protocol The protocol the TCPIPSERVICE has been set to use. implies The attribute and value that is required. option must be specified

Certain protocols require specific attributes and values e.g. protocol ECI requires SOCKETCLOSE to be set to NO.
Resolution:
Set the specified attribute to the required value.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0125 - CASRA0137


CASRA0134S Use of The attribute and value specified. option implies The attribute and value that is required. option must be specified

Certain attributes require other attributes and values e.g. AUTHENTICATE(CERTIFICATE) requires SSL to be set to CLIENTAUTH.
Resolution:
Set the specified attribute to the required value.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0125 - CASRA0137


CASRA0135W Protocol The protocol the TCPIPSERVICE has been set to use. implies URM. The default value has been assumed

The URM field is empty, so the default URM is specified.
Resolution:
None or specify a custom URM.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0125 - CASRA0137


CASRA0136W Transaction The new transaction the TCPIPSERVICE has been set to use. implies protocol The protocol the TCPIPSERVICE has been set to use., so protocol has been set to The protocol the TCPIPSERVICE has been set to use.

A pre-defined transaction has been specified with no protocol, so the protocol is set.#.
Resolution:
None or specify the protocol required.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0125 - CASRA0137


CASRA0137E The new transaction the TCPIPSERVICE has been set to use. option conflicts with The protocol the TCPIPSERVICE has been set to use. option and is ignored

A pre-defined transaction has been specified with no protocol, so the protocol is set.
Resolution:
None or specify the protocol required.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0125 - CASRA0137


CASRA1001 - CASRA1019

  • CASRA1001E Invalid request parameter
    The request passed in the parameter block rd-request-entry is in error or an invalid operation was attempted.
  • CASRA1002E Invalid command code passed in request parameter block
    An invalid command ID has been detected in the rd-request-command parameter entry.
  • CASRA1003E The RVDA value is not applicable for the requested command
    An RVDA was set to a value that is not applicable for the requested command id.
  • CASRA1004E The record type specified is not a valid value
    The request contained an invalid value set for the record type.
  • CASRA1005E Invalid pointer address
    An invalid address was present in the request parameter block. .
  • CASRA1006E Invalid length value
    An invalid length value was detected in the request parameter block.
  • CASRA1007E Invalid RVDA value
    An out of range RVDA value was passed in the request parameter block.
  • CASRA1008E Invalid RVDA value for the record type
    An RVDA was set to a value that is not applicable for the specified record type.
  • CASRA1009E A group name is required for this operation
    A resource group name must be specified for the record type being operated on.
  • CASRA1010E A resource name is required for this operation
    A resource name must be specified for the record type being operated on.
  • CASRA1011E A command was attempted that requires additional parameters
    The request command could not be processed because there were parameters missing.
  • CASRA1012E The requested record was not found
    An attempt was made to process a record that does not exist in the RDO file being processed.
  • CASRA1013E The requested group description record was not found
    An attempt was made to process a group that does not exist in the RDO file being processed.
  • CASRA1014E The record is locked by another process
    An attempt was made to process a record that is locked by another process. The update operation can not continue.
  • CASRA1015E The record is not locked and can not be updated
    An attempt was made to update a record which was not previously specified on a readupdate command and was not locked.
  • CASRA1016E Duplicate record found
    An attempt was made to add a record that already exists in the resource file being operated on. not locked.
  • CASRA1017E Invalid record type
    A request contained an invalid value set for the key record type.
  • CASRA1018E An IO error was encountered when processing the command
    An IO error occurred while processing the current record.
  • CASRA1019E An IO error was encountered when processing the command
    An IO error occurred while processing the current record.
Parent topic: CASRA Error Messages


CASRA1001E Invalid request parameter

The request passed in the parameter block rd-request-entry is in error or an invalid operation was attempted.
Resolution:
Correct the request and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1002E Invalid command code passed in request parameter block

An invalid command ID has been detected in the rd-request-command parameter entry.
Resolution:
Specify a valid command and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1003E The RVDA value is not applicable for the requested command

An RVDA was set to a value that is not applicable for the requested command id.
Resolution:
Correct the parameter and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1004E The record type specified is not a valid value

The request contained an invalid value set for the record type.
Resolution:
Correct the parameter and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1005E Invalid pointer address

An invalid address was present in the request parameter block. .
Resolution:
Correct the value and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1006E Invalid length value

An invalid length value was detected in the request parameter block.
Resolution:
Correct the value and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1007E Invalid RVDA value

An out of range RVDA value was passed in the request parameter block.
Resolution:
Correct the value and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1008E Invalid RVDA value for the record type

An RVDA was set to a value that is not applicable for the specified record type.
Resolution:
Correct the RVDA value and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1009E A group name is required for this operation

A resource group name must be specified for the record type being operated on.
Resolution:
Specify a resource group and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1010E A resource name is required for this operation

A resource name must be specified for the record type being operated on.
Resolution:
Specify a resource name and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1011E A command was attempted that requires additional parameters

The request command could not be processed because there were parameters missing.
Resolution:
Correct the request and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1012E The requested record was not found

An attempt was made to process a record that does not exist in the RDO file being processed.
Resolution:
Specify a valid record and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1013E The requested group description record was not found

An attempt was made to process a group that does not exist in the RDO file being processed.
Resolution:
Specify a valid group and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1014E The record is locked by another process

An attempt was made to process a record that is locked by another process. The update operation can not continue.
Resolution:
Investigate the cause of the record lock.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1015E The record is not locked and can not be updated

An attempt was made to update a record which was not previously specified on a readupdate command and was not locked.
Resolution:
Correct the error and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1016E Duplicate record found

An attempt was made to add a record that already exists in the resource file being operated on. not locked.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1017E Invalid record type

A request contained an invalid value set for the key record type.
Resolution:
Correct the record type and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1018E An IO error was encountered when processing the command

An IO error occurred while processing the current record.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1019E An IO error was encountered when processing the command

An IO error occurred while processing the current record.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1001 - CASRA1019


CASRA1020 - CASRA1032

  • CASRA1020E The resource definition file is read only
    A request to delete a record can not be processed because the target resource definition file is read only.
  • CASRA1021E The resource definition file is read only
    A request to read a record for update can not be processed because the target resource definition file is read only.
  • CASRA1022E The resource definition file is read only
    A request to add a record can not be processed because the target resource definition file is read only.
  • CASRA1023E The resource definition file is read only
    A request to update a record can not be processed because the target resource definition file is read only.
  • CASRA1024E The request entry count is greater than 500
    A request was passed the RDO API which had a value specified for rd-request-entry-count that is greater than the allowable limit of 500.
  • CASRA1025W The record is continued
    The last record read and returned by the RDO API is continued.
  • CASRA1026E New record version -some data may not be available
    A new version resource definition has been read some of the fields may not be shown. The cause is using an old version of MCO to process a resource definition file that has been upgraded to a later version.
  • CASRA1027E Old record version -the record should be upgraded
    An old version resource definition has been read; some of the fields may not be shown. The cause is using a new version of MCO to process a resource definition file that has not be upgraded to a later version.
  • CASRA1028E The record passed in not valid and can not be imported
    The record passed and requested for import that is not a valid import record format.
  • CASRA1029W End of file has been reached
    An end-of-file condition has been received during a browse request.
  • CASRA1030W Record truncated
    A record has been read form the resource definition file which is larger than the user's I/O buffer.
  • CASRA1031W Resource definition file is read only
    The resource definition file which the user has attempted to open is read only, and may not be updated.
  • CASRA1032E Key not contained within the specified record size
    The key length exceeds the given record size.
Parent topic: CASRA Error Messages


CASRA1020E The resource definition file is read only

A request to delete a record can not be processed because the target resource definition file is read only.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1020 - CASRA1032


CASRA1021E The resource definition file is read only

A request to read a record for update can not be processed because the target resource definition file is read only.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1020 - CASRA1032


CASRA1022E The resource definition file is read only

A request to add a record can not be processed because the target resource definition file is read only.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1020 - CASRA1032


CASRA1023E The resource definition file is read only

A request to update a record can not be processed because the target resource definition file is read only.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1020 - CASRA1032


CASRA1024E The request entry count is greater than 500

A request was passed the RDO API which had a value specified for rd-request-entry-count that is greater than the allowable limit of 500.
Resolution:
Correct the request and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1020 - CASRA1032


CASRA1025W The record is continued

The last record read and returned by the RDO API is continued.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1020 - CASRA1032


CASRA1026E New record version -some data may not be available

A new version resource definition has been read some of the fields may not be shown. The cause is using an old version of MCO to process a resource definition file that has been upgraded to a later version.
Resolution:
Process this record with a later version of MTS.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1020 - CASRA1032


CASRA1027E Old record version -the record should be upgraded

An old version resource definition has been read; some of the fields may not be shown. The cause is using a new version of MCO to process a resource definition file that has not be upgraded to a later version.
Resolution:
Either upgrade the file of upgrade this record.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1020 - CASRA1032


CASRA1028E The record passed in not valid and can not be imported

The record passed and requested for import that is not a valid import record format.
Resolution:
Correct the record and retry the import operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1020 - CASRA1032


CASRA1029W End of file has been reached

An end-of-file condition has been received during a browse request.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1020 - CASRA1032


CASRA1030W Record truncated

A record has been read form the resource definition file which is larger than the user's I/O buffer.
System Action:
The record is truncated.
Resolution:
Make the size of the I/O buffer bigger.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1020 - CASRA1032


CASRA1031W Resource definition file is read only

The resource definition file which the user has attempted to open is read only, and may not be updated.
Resolution:
If you wish to update the file, change its attributes to enable update processing.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1020 - CASRA1032


CASRA1032E Key not contained within the specified record size

The key length exceeds the given record size.
Resolution:
Correct either the key length or the record length.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA1020 - CASRA1032


CASRA1101 - CASRA1105

  • CASRA1101E A field or fields to be updated generated warning message(s)
    An attempt to add or update a record resulted in a field or fields being flagged in warning. The field(s) and the associated warning message are passed back in the user feedback area.
  • CASRA1102E A field or fields to be updated generated error message(s)
    An attempt to add or update a record resulted in a field or fields being flagged as invalid. The field(s) and the associated error message are passed back in the user feedback area.
  • CASRA1103E An invalid request was passed for the get-message command
    An attempt was made to obtain message text using the get-message command and the request was not properly formatted. ri-user-feedback-area was not set.
  • CASRA1104E An invalid request was passed for the get-message command
    An attempt was made to obtain message text using the get-message command and the request was not properly formatted. ri-user-feedback-entry was not set.
  • CASRA1105E An invalid request was passed for the get-message command
    An attempt was made to obtain message text using the get-message command and the request was not properly formatted. ri-message-return-area was not set.
Parent topic: CASRA Error Messages


CASRA1101E A field or fields to be updated generated warning message(s)

An attempt to add or update a record resulted in a field or fields being flagged in warning. The field(s) and the associated warning message are passed back in the user feedback area.
Resolution:
Review the warning messages.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1101 - CASRA1105


CASRA1102E A field or fields to be updated generated error message(s)

An attempt to add or update a record resulted in a field or fields being flagged as invalid. The field(s) and the associated error message are passed back in the user feedback area.
Resolution:
Review the warning messages.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1101 - CASRA1105


CASRA1103E An invalid request was passed for the get-message command

An attempt was made to obtain message text using the get-message command and the request was not properly formatted. ri-user-feedback-area was not set.
Resolution:
Correct the error and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1101 - CASRA1105


CASRA1104E An invalid request was passed for the get-message command

An attempt was made to obtain message text using the get-message command and the request was not properly formatted. ri-user-feedback-entry was not set.
Resolution:
Correct the error and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1101 - CASRA1105


CASRA1105E An invalid request was passed for the get-message command

An attempt was made to obtain message text using the get-message command and the request was not properly formatted. ri-message-return-area was not set.
Resolution:
Correct the error and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1101 - CASRA1105


CASRA1201 - CASRA1218

  • CASRA1201S Initialization failure
    A required support module was not present. not continue.
  • CASRA1202S Error processing the region configuration file
    While reading the regions configuration file and error was encountered and the operation can not continue.
  • CASRA1203S Initialization failure
    A required support module was not present.
  • CASRA1204S Initialization failure
    A required support module was not present.
  • CASRA1205S Initialization failure
    A required support module was not present.
  • CASRA1206S Initialization failure
    A required support module was not present.
  • CASRA1207S Initialization failure
    A required support module was not present.
  • CASRA1208S Initialization failure
    A required support module was not present.
  • CASRA1209S Initialization failure
    A required support module was not present.
  • CASRA1211S Error, incorrect resource definition file version
    The version of the resource definition file is not recognized.
  • CASRA1212E The resource definition file can not be found
    The file that is configured for the region being operated on can not be found.
  • CASRA1214E Error opening the resource definition file.
    An error was encountered while opening the resource definition file.
  • CASRA1215E Invalid request issued.
    A request was passed to the resource definition interface prior to it being properly initialized.
  • CASRA1216E The region name is not valid
    An override region name was passed on the initialization call and the region could not be found.
  • CASRA1217E Already initialized
    A initialization command was passed to the RDO API and it is already initialized.
  • CASRA1218S Initialization failure
    A required support module was not present.
Parent topic: CASRA Error Messages


CASRA1201S Initialization failure

A required support module was not present. not continue.
Resolution:
Investigate the cause of the missing module - dfh0cfg.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1201 - CASRA1218


CASRA1202S Error processing the region configuration file

While reading the regions configuration file and error was encountered and the operation can not continue.
Resolution:
Investigate the cause of error.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1201 - CASRA1218


CASRA1203S Initialization failure

A required support module was not present.
System Action:
Initialization terminates.
Resolution:
Investigate the cause of the missing module - dfh0ult.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1201 - CASRA1218


CASRA1204S Initialization failure

A required support module was not present.
System Action:
Initialization terminates.
Resolution:
Investigate the cause of the missing module - dfhextfh.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1201 - CASRA1218


CASRA1205S Initialization failure

A required support module was not present.
System Action:
Initialization terminates.
Resolution:
Investigate the cause of the missing module - dfherdio.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1201 - CASRA1218


CASRA1206S Initialization failure

A required support module was not present.
System Action:
Initialization terminates.
Resolution:
Investigate the cause of the missing module - dfherdcv.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1201 - CASRA1218


CASRA1207S Initialization failure

A required support module was not present.
System Action:
Initialization terminates.
Resolution:
Investigate the cause of the missing module - dfh0msg.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1201 - CASRA1218


CASRA1208S Initialization failure

A required support module was not present.
System Action:
Initialization terminates.
Resolution:
Investigate the cause of the missing module - dfhrval.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1201 - CASRA1218


CASRA1209S Initialization failure

A required support module was not present.
System Action:
Initialization terminates.
Resolution:
Investigate the cause of the missing module - dfhrmsg.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1201 - CASRA1218


CASRA1211S Error, incorrect resource definition file version

The version of the resource definition file is not recognized.
System Action:
The request is not processed.
Resolution:
Check that the resource definition file is the intended file and that it is the proper version.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1201 - CASRA1218


CASRA1212E The resource definition file can not be found

The file that is configured for the region being operated on can not be found.
System Action:
The request is not processed.
Resolution:
Correct your configuration and then retry the operation.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1201 - CASRA1218


CASRA1214E Error opening the resource definition file.

An error was encountered while opening the resource definition file.
System Action:
The request is not processed.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1201 - CASRA1218


CASRA1215E Invalid request issued.

A request was passed to the resource definition interface prior to it being properly initialized.
System Action:
The request is not processed.
Resolution:
Initialize the interface and retry the request.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1201 - CASRA1218


CASRA1216E The region name is not valid

An override region name was passed on the initialization call and the region could not be found.
System Action:
Initialization fails.
Resolution:
Specify a valid region name.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1201 - CASRA1218


CASRA1217E Already initialized

A initialization command was passed to the RDO API and it is already initialized.
System Action:
The request is not processed.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1201 - CASRA1218


CASRA1218S Initialization failure

A required support module was not present.
System Action:
Initialization terminates.
Resolution:
Investigate the cause of the missing module - dfhrapi.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRA1201 - CASRA1218


CASRA1301 - CASRA1319

  • CASRA1301E The USERID entered is not valid
    A initialization command was passed a userid that is not defined in the target resource definition file.
  • CASRA1302E The PASSWORD entered in not valid
    A initialization command was passed a password that is not defined in the target resource definition file.
  • CASRA1303E Authorization failed
    An attempt was made to access a resource that you did not have the proper authority for.
  • CASRA1304E Authorization failed for PCT table access
    An attempt was made to access a PCT entry and the user does not have the proper authority level.
  • CASRA1305E Authorization failed for FCT table access
    An attempt was made to access a FCT entry and the user does not have the proper authority level.
  • CASRA1306E Authorization failed for PPT table access
    An attempt was made to access a PPT entry and the user does not have the proper authority level.
  • CASRA1307E Authorization failed for DCT table access
    An attempt was made to access a DCT entry and the user does not have the proper authority level.
  • CASRA1308E Authorization failed for SIT table access
    An attempt was made to access a PCT entry and the user does not have the proper authority level.
  • CASRA1309E Authorization failed for SNT table access
    An attempt was made to access a SNT entry and the user does not have the proper authority level.
  • CASRA1310E Authorization failed for TST table access
    An attempt was made to access a TST entry and the user does not have the proper authority level.
  • CASRA1311E Authorization failed for JCT access
    An attempt was made to access a JCT entry and the user does not have the proper authority level.
  • CASRA1312E Authorization failed for TYPE TERM table access
    An attempt was made to access a TTYPE entry and the user does not have the proper authority level.
  • CASRA1313E Authorization failed for TERM table access
    An attempt was made to access a TERM entry and the user does not have the proper authority level.
  • CASRA1314E Authorization failed for PLT table access
    An attempt was made to access a PLT entry and the user does not have the proper authority level.
  • CASRA1315E Authorization failed for STARTUP table access
    An attempt was made to access a STARTUP entry and the user does not have the proper authority level.
  • CASRA1316E Authorization failed for XLT access
    An attempt was made to access a XLT entry and the user does not have the proper authority level.
  • CASRA1317E Authorization failed for PRO table access
    An attempt was made to access a PRO entry and the user does not have the proper authority level.
  • CASRA1318E Authorization failed for security record access
    An attempt was made to access a RID entry and the user does not have the proper authority level.
  • CASRA1319E Authorization failed for group description table access
    An attempt was made to access a RID entry and the user does not have the proper authority level.
Parent topic: CASRA Error Messages


CASRA1301E The USERID entered is not valid

A initialization command was passed a userid that is not defined in the target resource definition file.
System Action:
The request is not processed.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1302E The PASSWORD entered in not valid

A initialization command was passed a password that is not defined in the target resource definition file.
System Action:
The request is not processed.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1303E Authorization failed

An attempt was made to access a resource that you did not have the proper authority for.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1304E Authorization failed for PCT table access

An attempt was made to access a PCT entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1305E Authorization failed for FCT table access

An attempt was made to access a FCT entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1306E Authorization failed for PPT table access

An attempt was made to access a PPT entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1307E Authorization failed for DCT table access

An attempt was made to access a DCT entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1308E Authorization failed for SIT table access

An attempt was made to access a PCT entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1309E Authorization failed for SNT table access

An attempt was made to access a SNT entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1310E Authorization failed for TST table access

An attempt was made to access a TST entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1311E Authorization failed for JCT access

An attempt was made to access a JCT entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1312E Authorization failed for TYPE TERM table access

An attempt was made to access a TTYPE entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1313E Authorization failed for TERM table access

An attempt was made to access a TERM entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1314E Authorization failed for PLT table access

An attempt was made to access a PLT entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1315E Authorization failed for STARTUP table access

An attempt was made to access a STARTUP entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1316E Authorization failed for XLT access

An attempt was made to access a XLT entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1317E Authorization failed for PRO table access

An attempt was made to access a PRO entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1318E Authorization failed for security record access

An attempt was made to access a RID entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1319E Authorization failed for group description table access

An attempt was made to access a RID entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1301 - CASRA1319


CASRA1320 - CASRA1326

  • CASRA1320E The file is secure and a valid user has not signed on
    An attempt was made to access a resource file and a proper user passed as part or RDO API initialization.
  • CASRA1321E Access to the resource was denied
    An attempt was made to access a resource and the user does not have the proper authorization level.
  • CASRA1322E The resource file security setting was not updated
    An attempt was made to access a resource and the user does not have the proper authorization level.
  • CASRA1324E No user is signed on
    An attempt was made to access a resource and no user had signed on.
  • CASRA1325E Authorization failed for XAT access
    An attempt was made to access an XAT entry and the user does not have the proper authority level.
  • CASRA1326E Resource definition security must be OFF prior to resource import
    Resource cannot be imported into a secure resource definition file.
Parent topic: CASRA Error Messages


CASRA1320E The file is secure and a valid user has not signed on

An attempt was made to access a resource file and a proper user passed as part or RDO API initialization.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1320 - CASRA1326


CASRA1321E Access to the resource was denied

An attempt was made to access a resource and the user does not have the proper authorization level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1320 - CASRA1326


CASRA1322E The resource file security setting was not updated

An attempt was made to access a resource and the user does not have the proper authorization level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1320 - CASRA1326


CASRA1324E No user is signed on

An attempt was made to access a resource and no user had signed on.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1320 - CASRA1326


CASRA1325E Authorization failed for XAT access

An attempt was made to access an XAT entry and the user does not have the proper authority level.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1320 - CASRA1326


CASRA1326E Resource definition security must be OFF prior to resource import

Resource cannot be imported into a secure resource definition file.
System Action:
The request is not processed.
Resolution:
Remove security from resource definition file and try again.
Module:
dfhrdtup
Destination:
standard error
Parent topic: CASRA1320 - CASRA1326


CASRA1501 - CASRA1515

  • CASRA1501S An unrecognised error has occured - file may be corrupt
    An error occured which has not been recognised. The resource definition file may be corrupt.
  • CASRA1502E The requested record was not found
    An attempt was made to process a record that does not exist in the RDO file being processed.
  • CASRA1503E Duplicate record found
    An attempt was made to add a record that already exists in the resource file being operated on. not locked.
  • CASRA1504E The record is locked by another process
    An attempt was made to process a record that is locked by another process. The update operation can not continue.
  • CASRA1505E The resource definition file ((substDir$)) cannot be found
    The file that is configured for the region being operated on can not be found.
  • CASRA1506E Invalid record type
    A request contained an invalid value set for the key record type.
  • CASRA1507E Invalid request issued
    An invalid request was passed to the resource definition interface prior to it being properly initialized.
  • CASRA1508S A mis-match error has occured
    A mis-match error has occured.
  • CASRA1509E Failed to create resource definition file ((substDir$))
    An attempt to create a new resource definition file failed.
  • CASRA1510E Error opening the resource definition file ((substDir$))
    An error was encountered while opening the resource definition file.
  • CASRA1511S Initialization failure
    A required support module was not present. not continue.
  • CASRA1512E The resource definition file ((substDir$)) is already open
    Attempt to open a resource definition file failed because the file was alerady open.
  • CASRA1513S The resource definition file ((substDir$)) version is incorrect
    The version of the resource definition file is not recognized.
  • CASRA1514E The resource definition file ((substDir$)) is secure and a valid user has not signed on
    An attempt was made to access a resource file and a proper user passed as part or RDO API initialization.
  • CASRA1515E An I/O error ((substFS$)) was encountered accessing the resource definition file ((substDir$))
    An IO error occurred while processing the current record.
Parent topic: CASRA Error Messages


CASRA1501S An unrecognised error has occured - file may be corrupt

An error occured which has not been recognised. The resource definition file may be corrupt.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA1501 - CASRA1515


CASRA1502E The requested record was not found

An attempt was made to process a record that does not exist in the RDO file being processed.
Resolution:
Specify a valid record and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1501 - CASRA1515


CASRA1503E Duplicate record found

An attempt was made to add a record that already exists in the resource file being operated on. not locked.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1501 - CASRA1515


CASRA1504E The record is locked by another process

An attempt was made to process a record that is locked by another process. The update operation can not continue.
Resolution:
Investigate the cause of the record lock.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1501 - CASRA1515


CASRA1505E The resource definition file ((substDir$)) cannot be found

The file that is configured for the region being operated on can not be found.
System Action:
The request is not processed.
Resolution:
Correct your configuration and then retry the operation.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1501 - CASRA1515


CASRA1506E Invalid record type

A request contained an invalid value set for the key record type.
Resolution:
Correct the record type and retry the operation.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1501 - CASRA1515


CASRA1507E Invalid request issued

An invalid request was passed to the resource definition interface prior to it being properly initialized.
System Action:
The request is not processed.
Resolution:
Initialize the interface and retry the request.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1501 - CASRA1515


CASRA1508S A mis-match error has occured

A mis-match error has occured.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA1501 - CASRA1515


CASRA1509E Failed to create resource definition file ((substDir$))

An attempt to create a new resource definition file failed.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA1501 - CASRA1515


CASRA1510E Error opening the resource definition file ((substDir$))

An error was encountered while opening the resource definition file.
System Action:
The request is not processed.
Module:
RDOWrapper
Destination:
standard error
Parent topic: CASRA1501 - CASRA1515


CASRA1511S Initialization failure

A required support module was not present. not continue.
Resolution:
Verify installation.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA1501 - CASRA1515


CASRA1512E The resource definition file ((substDir$)) is already open

Attempt to open a resource definition file failed because the file was alerady open.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA1501 - CASRA1515


CASRA1513S The resource definition file ((substDir$)) version is incorrect

The version of the resource definition file is not recognized.
System Action:
The request is not processed.
Resolution:
Check that the resource definition file is the intended file and that it is the proper version.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1501 - CASRA1515


CASRA1514E The resource definition file ((substDir$)) is secure and a valid user has not signed on

An attempt was made to access a resource file and a proper user passed as part or RDO API initialization.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrapi
Destination:
standard error
Parent topic: CASRA1501 - CASRA1515


CASRA1515E An I/O error ((substFS$)) was encountered accessing the resource definition file ((substDir$))

An IO error occurred while processing the current record.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA1501 - CASRA1515


CASRB Error Messages

  • CASRB0001 - CASRB0019
  • CASRB0020 - CASRB0039
  • CASRB0040 - CASRB0059
  • CASRB0060 - CASRB0079
Parent topic: Enterprise Server Error Messages


CASRB0001 - CASRB0019

  • CASRB0001I No resource records found
    There were no records of the specified type to list.
  • CASRB0002I Already at the top of the list
    You cannot page up as there are no more records of the specified type preceding those displayed.
  • CASRB0003I Already at the bottom of the list
    You cannot page down as there are no more records of the specified type following the last one displayed.
  • CASRB0004I Record added
    The record was successfully added to the file.
  • CASRB0005E Resource name is invalid
    The resource name entered was invalid.
  • CASRB0006I Record updated
    The record has been successfully updated.
  • CASRB0007I Record deleted
    The record has been successfully deleted.
  • CASRB0008I Read only access allowed
    The record has been successfully deleted.
  • CASRB0009E Access to the resource was denied
    An attempt was made to access a resource for which the user does not have the proper authorization.
  • CASRB0010I Resource definition file has been upgraded
    The resource definition file has been upgraded to the latest level. All resources are now at the current level.
  • CASRB0011E Group name is invalid
    The group name entered was invalid.
  • CASRB0012I Group deleted
    The group has been successfully deleted.
  • CASRB0013I No group records found
    There where no records of the specified type to list.
  • CASRB0014I Please verify the password by entering it in verify password field
    As the password is non-display it needs to be entered twice to ensure that it is correct.
  • CASRB0015E Verify password does not match password
    The password and verify password fields must contain the same value.
  • CASRB0016E Please specify either fixed or free format open string not both
    Only a fixed format or free format open string can be specified.
  • CASRB0017E This action requires resource-type update authority
    The requested action requires Update authority for resource-type, which you do not have.
  • CASRB0018W Resource definition file has been upgraded with errors
    Some resource definition records could not be upgraded automatically.
  • CASRB0019E Error opening log file (rdoupgrd.log), status=file-status
    An unexpected file-status was received when attempting to open the dfhpcupg log file (rdoupgrd.log) in the same directory as the input RDF file. The file is opened in EXTEND mode.
Parent topic: CASRB Error Messages


CASRB0001I No resource records found

There were no records of the specified type to list.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0001 - CASRB0019


CASRB0002I Already at the top of the list

You cannot page up as there are no more records of the specified type preceding those displayed.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0001 - CASRB0019


CASRB0003I Already at the bottom of the list

You cannot page down as there are no more records of the specified type following the last one displayed.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0001 - CASRB0019


CASRB0004I Record added

The record was successfully added to the file.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0001 - CASRB0019


CASRB0005E Resource name is invalid

The resource name entered was invalid.
Resolution:
Correct the resource name.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0001 - CASRB0019


CASRB0006I Record updated

The record has been successfully updated.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0001 - CASRB0019


CASRB0007I Record deleted

The record has been successfully deleted.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0001 - CASRB0019


CASRB0008I Read only access allowed

The record has been successfully deleted.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0001 - CASRB0019


CASRB0009E Access to the resource was denied

An attempt was made to access a resource for which the user does not have the proper authorization.
System Action:
The request is not processed.
Resolution:
Contact your system administrator.
Module:
dfhrdef
Destination:
standard error
Parent topic: CASRB0001 - CASRB0019


CASRB0010I Resource definition file has been upgraded

The resource definition file has been upgraded to the latest level. All resources are now at the current level.
Module:
dfhrdef
Destination:
standard error
Parent topic: CASRB0001 - CASRB0019


CASRB0011E Group name is invalid

The group name entered was invalid.
Resolution:
Correct the resource name.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0001 - CASRB0019


CASRB0012I Group deleted

The group has been successfully deleted.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0001 - CASRB0019


CASRB0013I No group records found

There where no records of the specified type to list.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0001 - CASRB0019


CASRB0014I Please verify the password by entering it in verify password field

As the password is non-display it needs to be entered twice to ensure that it is correct.
Resolution:
Key the password into the verify password field.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0001 - CASRB0019


CASRB0015E Verify password does not match password

The password and verify password fields must contain the same value.
Resolution:
Correct either password or verify password fields.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0001 - CASRB0019


CASRB0016E Please specify either fixed or free format open string not both

Only a fixed format or free format open string can be specified.
Resolution:
Delete either the fixed or free format open string.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0001 - CASRB0019


CASRB0017E This action requires resource-type update authority

The requested action requires Update authority for resource-type, which you do not have.
System Action:
The request is rejected.
Resolution:
Delete either the fixed or free format open string. Contact your system security administrator.
Module:
dfhrdef
Destination:
user screen
Parent topic: CASRB0001 - CASRB0019


CASRB0018W Resource definition file has been upgraded with errors

Some resource definition records could not be upgraded automatically.
Resolution:
Read the resource definition upgrade logfile and upgrade the RDF using dfhpcupg.
Module:
dfhrdef
Destination:
standard error
Parent topic: CASRB0001 - CASRB0019


CASRB0019E Error opening log file (rdoupgrd.log), status=file-status

An unexpected file-status was received when attempting to open the dfhpcupg log file (rdoupgrd.log) in the same directory as the input RDF file. The file is opened in EXTEND mode.
System Action:
Processing continues without logging.
Resolution:
Look up the file-status and handle accordingly.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0001 - CASRB0019


CASRB0020 - CASRB0039

  • CASRB0020I Upgrading file filespec
    Informational message to indicate the full %1$i of the Resource Definition Facility (RDF) file being upgraded. RDF files often need to be upgraded when a new version of MTS/CICS Option is installed, in order to ensure ongoing compatibility and exploit new features.
  • CASRB0021I Run at date time using upgrade version 'program-version'
    Informational message to indicate the date, time and program-version used to upgrade your RDF file.
  • CASRB0022I Resource Definition file at correct level. No upgrade required.
    The entries in your Resource Definition file were all current.
  • CASRB0023W count typeterm entries were bypassed due to page size conflict
    The Resource Definition file upgrade (dfhpcupg) flags Typeterm definitions whose settings for "Mapping Page Size" and "Device Screen Size" do not match, since this is often unintentional.
  • CASRB0024W Typeterm group.resource mapping pagesize and device screen size differ
    The named Typeterm definition contains a Mapping pagesize setting different than its Device screen size setting, which is often unintentional. See also message TXRB0023W.
  • CASRB0025I Upgrade log file: filespec
    Informational message to indicate the full %1$i of the log file where RDF upgrade messages are written.
  • CASRB0026I Added resource-type entry resource
    The named Resource Definition Facility (RDF) entry was successfully upgraded. When you execute the RDF upgrade utility (dfhpcupg), any additions and changes to the suite of standard system definitions are applied to your RDF file, and any user definitions are upgraded to reflect the new internal data structures.
  • CASRB0027I Added resource-type group group entry resource
    The named Resource Definition Facility (RDF) entry was successfully added. When you execute the RDF upgrade utility (dfhpcupg), any additions and changes to the suite of standard system definitions are applied to your RDF file, and any user definitions are upgraded to reflect the new internal data structures.
  • CASRB0028I Checking supplied system entries
    The Resource Definition file upgrade utility (dfhrdef) is beginning to check the supplied system entries, to determine whether they require upgrading. The internal structure of the RDF file often changes between releases, so executing the upgrade utility (dfhpcupg) is recommended.
  • CASRB0029I Checking user-defined entries
    The Resource Definition file upgrade utility (dfhrdef) is beginning to check any user-defined entries, to determine whether they require upgrading. The internal structure of the RDF file often changes between releases, so executing the upgrade utility (dfhpcupg) is recommended.
  • CASRB0030I Adding/updating resource-type entries
    The Resource Definition file upgrade utility (dfhrdef) is beginning to upgrade resource-type entries. The internal structure of the RDF file often changes between releases, so executing the upgrade utility (dfhpcupg) is recommended.
  • CASRB0031E Unexpected error writing to log file (rdoupgrd.log), status=file-status
    An unexpected file-status was received when attempting to write to the dfhpcupg log file (rdoupgrd.log).
  • CASRB0032E Unexpected error loading module module-name
    module-name cannot be found, or there was a system error loading it. The module is searched for in $TXDIR/lib, then in the current directory.
  • CASRB0033F Resource file version not compatible with dfherdio
    The Resource Definition I/O module is incompatible with the RDF file you are using. RDF files are forward compatible, but not backward compatible.
  • CASRB0034F Resource file not at the same level as dferdio
    Resource file not at the same level as dferdio
  • CASRB0035E Conversion Table File not found
    Your conversion file (dfhdrcnv) was not found.
  • CASRB0036E Unexpected dfherdcv error: request=request-code result=result-code status=file-status
    An unexpected error was returned from the conversion file I/O handler (dfherdcv).
  • CASRB0037E A valid SNT administrator sign-on is required to toggle security.
    You have not identified yourself as a user with SNT-Update authority, which is required in order to toggle security on or off.
  • CASRB0038E Error reading security record. Security unchanged.
    An unexpected error occurred reading the RDF security record, preventing the changing of security settings. This message will be preceded by TXRB0043E detailing the specific error.
  • CASRB0039W Security is already enabled - no change made
    You have requested that RDF security be enabled, but it is already enabled.
Parent topic: CASRB Error Messages


CASRB0020I Upgrading file filespec

Informational message to indicate the full %1$i of the Resource Definition Facility (RDF) file being upgraded. RDF files often need to be upgraded when a new version of MTS/CICS Option is installed, in order to ensure ongoing compatibility and exploit new features.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0021I Run at date time using upgrade version 'program-version'

Informational message to indicate the date, time and program-version used to upgrade your RDF file.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0022I Resource Definition file at correct level. No upgrade required.

The entries in your Resource Definition file were all current.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0023W count typeterm entries were bypassed due to page size conflict

The Resource Definition file upgrade (dfhpcupg) flags Typeterm definitions whose settings for "Mapping Page Size" and "Device Screen Size" do not match, since this is often unintentional.
System Action:
The flagged Typeterm entries are not upgraded.
Resolution:
Review the flagged Typeterm entries (indicated by message TXRB0024W). Then either manually adjust them in dfhrdef, or run the upgrade process (dfhpcupg) again, specifying /t= (force pagesize = device size) or /td (allow sizes to differ).
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0024W Typeterm group.resource mapping pagesize and device screen size differ

The named Typeterm definition contains a Mapping pagesize setting different than its Device screen size setting, which is often unintentional. See also message TXRB0023W.
System Action:
The Typeterm entry is not upgraded.
Resolution:
Either manually adjust these values in dfhrdef, or run the upgrade process (dfhpcupg) again, specifying /t= (force pagesize = device size) or /td (allow sizes to differ).
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0025I Upgrade log file: filespec

Informational message to indicate the full %1$i of the log file where RDF upgrade messages are written.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0026I Added resource-type entry resource

The named Resource Definition Facility (RDF) entry was successfully upgraded. When you execute the RDF upgrade utility (dfhpcupg), any additions and changes to the suite of standard system definitions are applied to your RDF file, and any user definitions are upgraded to reflect the new internal data structures.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0027I Added resource-type group group entry resource

The named Resource Definition Facility (RDF) entry was successfully added. When you execute the RDF upgrade utility (dfhpcupg), any additions and changes to the suite of standard system definitions are applied to your RDF file, and any user definitions are upgraded to reflect the new internal data structures.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0028I Checking supplied system entries

The Resource Definition file upgrade utility (dfhrdef) is beginning to check the supplied system entries, to determine whether they require upgrading. The internal structure of the RDF file often changes between releases, so executing the upgrade utility (dfhpcupg) is recommended.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0029I Checking user-defined entries

The Resource Definition file upgrade utility (dfhrdef) is beginning to check any user-defined entries, to determine whether they require upgrading. The internal structure of the RDF file often changes between releases, so executing the upgrade utility (dfhpcupg) is recommended.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0030I Adding/updating resource-type entries

The Resource Definition file upgrade utility (dfhrdef) is beginning to upgrade resource-type entries. The internal structure of the RDF file often changes between releases, so executing the upgrade utility (dfhpcupg) is recommended.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0031E Unexpected error writing to log file (rdoupgrd.log), status=file-status

An unexpected file-status was received when attempting to write to the dfhpcupg log file (rdoupgrd.log).
System Action:
Processing continues without further logging.
Resolution:
Look up the file-status and handle accordingly.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0020 - CASRB0039


CASRB0032E Unexpected error loading module module-name

module-name cannot be found, or there was a system error loading it. The module is searched for in $TXDIR/lib, then in the current directory.
System Action:
Processing may continue, if the module is not critical.
Resolution:
Check that $TXDIR is set correctly and that module-name exists in $TXDIR/lib.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0033F Resource file version not compatible with dfherdio

The Resource Definition I/O module is incompatible with the RDF file you are using. RDF files are forward compatible, but not backward compatible.
System Action:
Processing terminated.
Resolution:
Check that you are not using a newer RDF file with an older version of this system.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0034F Resource file not at the same level as dferdio

Resource file not at the same level as dferdio
System Action:
Processing terminated.
Resolution:
Check that you are not using a newer RDF file with an older version of this system.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0035E Conversion Table File not found

Your conversion file (dfhdrcnv) was not found.
System Action:
Processing of the conversion file ends.
Resolution:
Check that the dfhdrcnv and dfhdrcnv.idx files exist in your $TXDIR/files/sys or $REGIONBASE/{region}/files/reg subdirectory.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0036E Unexpected dfherdcv error: request=request-code result=result-code status=file-status

An unexpected error was returned from the conversion file I/O handler (dfherdcv).
System Action:
The file is closed (if it was open), and processing continues, if possible.
Resolution:
file-status may provide some insight into the cause of the problem. If not, contact Product Support.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0037E A valid SNT administrator sign-on is required to toggle security.

You have not identified yourself as a user with SNT-Update authority, which is required in order to toggle security on or off.
System Action:
Processing continues with activities that do not require this authority.
Resolution:
Provide /u{userid} and /p{password} parameters for a user with SNT-Update authority.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0038E Error reading security record. Security unchanged.

An unexpected error occurred reading the RDF security record, preventing the changing of security settings. This message will be preceded by TXRB0043E detailing the specific error.
System Action:
Processing continues without toggling security.
Resolution:
Contact Product Support.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0039W Security is already enabled - no change made

You have requested that RDF security be enabled, but it is already enabled.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0020 - CASRB0039


CASRB0040 - CASRB0059

  • CASRB0040W Security is already disabled - no change made
    You have requested that RDF security be disabled, but it is already disabled.
  • CASRB0041I Security has been enabled.
    Your request to enable RDF security was successful.
  • CASRB0042I Security has been disabled.
    Your request to disable RDF security was successful.
  • CASRB0043E Cannot access Resource Definition File - status=file-status (req=request-code res=result-code)
    An unexpected error was returned from the Resource Definition file I/O handler (dfherdio).
  • CASRB0044E Invalid userid/password
    You have provided an invalid userid and/or password.
  • CASRB0045E Specified userid does not have SNT Update authority
    The userid you have provided does not have SNT-Update authority, which is required to perform a requested activity.
  • CASRB0046I Upgrading RDF security data
    The system is upgrading an older RDF file by adding security configuration details. Subsequent messages indicate whether security is initially enabled or disabled.
  • CASRB0047I An unaltered SYSAD userid exists-- security default is disabled.
    The system is upgrading an older RDF file by adding security configuration details. Security is initially disabled, since the installation default userid (SYSAD) still exists with the original password (SYSAD).
  • CASRB0048I has SNT-Update authority-- security default is enabled.
    The system is upgrading an older RDF file by adding security configuration details. Security is initially enabled, since the installation default userid (SYSAD) was not found with its original password (SYSAD), and at least one userid was found with SNT-Update authority.
  • CASRB0049I No users with SNT-Update authority-- security default is disabled.
    The system is upgrading an older RDF file by adding security configuration details. Security is initially disabled, since no userid was found with SNT-Update authority.
  • CASRB0050F Fatal error. Program cannot continue
    The program has encountered an unrecoverable or corruptible situation, so is terminating abnormally.
  • CASRB0051I RDF backup file backup-filespec created
    You have requested a backup be taken of the RDF file before upgrading, and it was successfully completed.
  • CASRB0052F Resource Definition backup failed, status=status-code
    You have requested a backup be taken of the RDF file before upgrading, and it failed.
  • CASRB0053E Command parameter error: parameter
    parameter is invalid for this command line.
  • CASRB0054I Upgraded resource-type entry resource
    The named Resource Definition Facility (RDF) entry was successfully upgraded. When you execute the RDF upgrade utility (dfhpcupg), any additions and changes to the suite of standard system definitions are applied to your RDF file, and any user definitions are upgraded to reflect the new internal data structures.
  • CASRB0055I Upgraded resource-type group group entry resource
    The named Resource Definition Facility (RDF) entry was successfully upgraded. When you execute the RDF upgrade utility (dfhpcupg), any additions and changes to the suite of standard system definitions are applied to your RDF file, and any user definitions are upgraded to reflect the new internal data structures.
  • CASRB0056I Processing completed with return-code=return-code
    The Resource Definition Facility (RDF) upgrade utility (dfhpcupg) has completed with return-code.
  • CASRB0057I Detected zero PCT security key in group group entry resource
    The security key for the named PCT entry has a value of zero. When security is turned on the transaction will cause a violation. Re-run dfhpcupg with the /z option to automatically reset all PCT zero security-key entries to have the '01' key turned on, or alter the value manually using the Resource Definition Facility (dfhrdef).
  • CASRB0058I This resource is not selectable. Use the GUI in Mainframe Express
    Viewing and updating FCTs, PCTs and PPTs is now done via graphical user interface within Mainframe Express. The listing of resources has been retained to avoid deleting groups that look as though they are empty.
  • CASRB0059W Data set dsname not found in catalog.
    During the import of a file definition, a DSNAME was specified that was not found in the catalog. As the catalog is used to determine the real PC file name, accessing the file in CICS Option will cause a failure at run time.
Parent topic: CASRB Error Messages


CASRB0040W Security is already disabled - no change made

You have requested that RDF security be disabled, but it is already disabled.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0041I Security has been enabled.

Your request to enable RDF security was successful.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0042I Security has been disabled.

Your request to disable RDF security was successful.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0043E Cannot access Resource Definition File - status=file-status (req=request-code res=result-code)

An unexpected error was returned from the Resource Definition file I/O handler (dfherdio).
System Action:
The file is closed (if it was open), and processing continues, if possible.
Resolution:
file-status may provide some insight into the cause of the problem. If not, contact Product Support.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0044E Invalid userid/password

You have provided an invalid userid and/or password.
System Action:
Processing continues with activities that do not require a valid logon.
Resolution:
Provide valid /u{userid} and /p{password} parameters.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0045E Specified userid does not have SNT Update authority

The userid you have provided does not have SNT-Update authority, which is required to perform a requested activity.
System Action:
Processing continues with activities that do not require this authority.
Resolution:
Provide /u{userid} and /p{password} parameters for a user with SNT-Update authority.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0046I Upgrading RDF security data

The system is upgrading an older RDF file by adding security configuration details. Subsequent messages indicate whether security is initially enabled or disabled.
System Action:
Security defaults to enabled ONLY if you have - Deleted or changed the password for user SYSAD, and - At least one user has SNT-Update authority.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0047I An unaltered SYSAD userid exists-- security default is disabled.

The system is upgrading an older RDF file by adding security configuration details. Security is initially disabled, since the installation default userid (SYSAD) still exists with the original password (SYSAD).
System Action:
System security defaults to disabled.
Resolution:
If you want security on your system, change the password for the SYSAD userid.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0048I has SNT-Update authority-- security default is enabled.

The system is upgrading an older RDF file by adding security configuration details. Security is initially enabled, since the installation default userid (SYSAD) was not found with its original password (SYSAD), and at least one userid was found with SNT-Update authority.
System Action:
System security defaults to enabled.
Resolution:
If you do not want security on your system, run dfhpcupg with the /u /p and /ss- parameters.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0049I No users with SNT-Update authority-- security default is disabled.

The system is upgrading an older RDF file by adding security configuration details. Security is initially disabled, since no userid was found with SNT-Update authority.
System Action:
System security defaults to disabled.
Resolution:
If you do not want security on your system, run dfhpcupg with the /u /p and /ss- parameters. If you want security on your system, create a userid with SNT-Update authority, then run dfhpcupg with the /u /p and /ss+ parameters.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0050F Fatal error. Program cannot continue

The program has encountered an unrecoverable or corruptible situation, so is terminating abnormally.
System Action:
The program terminates abnormally.
Resolution:
Examine prior messages for details of the problem.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0051I RDF backup file backup-filespec created

You have requested a backup be taken of the RDF file before upgrading, and it was successfully completed.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0052F Resource Definition backup failed, status=status-code

You have requested a backup be taken of the RDF file before upgrading, and it failed.
System Action:
Processing is terminated.
Resolution:
Look up status-code in the COBOL System Reference for CBL_COPY_FILE status values.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0053E Command parameter error: parameter

parameter is invalid for this command line.
System Action:
Command processing terminates.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0040 - CASRB0059


CASRB0054I Upgraded resource-type entry resource

The named Resource Definition Facility (RDF) entry was successfully upgraded. When you execute the RDF upgrade utility (dfhpcupg), any additions and changes to the suite of standard system definitions are applied to your RDF file, and any user definitions are upgraded to reflect the new internal data structures.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0055I Upgraded resource-type group group entry resource

The named Resource Definition Facility (RDF) entry was successfully upgraded. When you execute the RDF upgrade utility (dfhpcupg), any additions and changes to the suite of standard system definitions are applied to your RDF file, and any user definitions are upgraded to reflect the new internal data structures.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0056I Processing completed with return-code=return-code

The Resource Definition Facility (RDF) upgrade utility (dfhpcupg) has completed with return-code.
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0057I Detected zero PCT security key in group group entry resource

The security key for the named PCT entry has a value of zero. When security is turned on the transaction will cause a violation. Re-run dfhpcupg with the /z option to automatically reset all PCT zero security-key entries to have the '01' key turned on, or alter the value manually using the Resource Definition Facility (dfhrdef).
Module:
dfhpcupg
Destination:
Stdout and rdoupgrd.log
Parent topic: CASRB0040 - CASRB0059


CASRB0058I This resource is not selectable. Use the GUI in Mainframe Express

Viewing and updating FCTs, PCTs and PPTs is now done via graphical user interface within Mainframe Express. The listing of resources has been retained to avoid deleting groups that look as though they are empty.
System Action:
Access to the resource is denied.
Resolution:
Select the entry via the CICS tab in MFE.
Module:
dfhrdef
Destination:
standard error
Parent topic: CASRB0040 - CASRB0059


CASRB0059W Data set dsname not found in catalog.

During the import of a file definition, a DSNAME was specified that was not found in the catalog. As the catalog is used to determine the real PC file name, accessing the file in CICS Option will cause a failure at run time.
System Action:
The FCT record is created as given.
Resolution:
Create the data set using DELETE/DEFINE or interactive AMS.
Module:
dfhrdtup
Destination:
Build tab
Parent topic: CASRB0040 - CASRB0059


CASRB0060 - CASRB0079

  • CASRB0060E Failed to open catalog. Return code = return-code
    During the import of resource definitions, a bad return code was detected while trying to open the catalog.
  • CASRB0070I Modified FCT entry FCT-name in group group-name, FS Server ID was "Old-FS-ID" now "New-FS-ID"
    The FCT resource record was modified to bulk change the Fileshare server ID. The previous and new Fileshare server IDs are displayed.
  • CASRB0071I Processing FCT entries in group group-name, bulk update of Fileshare server (FS-ID)
    Setting all FCT entries in the group to the specified Fileshare server ID.
  • CASRB0072I Group group-name not found
    The specified group is not found in the RDT.
  • CASRB0073E Group group-name is invalid
    The specified group name contains invalid characters.
  • CASRB0074E Resource definition path not specified
    The resource definition path has not been specified on the command line.
  • CASRB0075E Options /s(sit-name,FS-ID) and /f(group-name,FS-ID) mutually exclusives
    Both parameters /ssit-name and /f(group-name...) were requested but only one of them can be requested at a time.
  • CASRB0076E SIT sit-name contains invalid characters
    The name of the SIT contains invalid characters.
  • CASRB0077E SIT sit-name not found
    The name of the SIT does not exist.
  • CASRB0078I Modified SIT sit-name. FS-ID for recoverable TS was old-recoverable-TS-name now new-recoverable-TS/TD-name.
    The name of the FS-ID for recoverable TS/TD has changed.
  • CASRB0079I Modified SIT sit-name. FS-ID for recoverable TD was old-recoverable-TS-name now new-recoverable-TS/TD-name.
    The name of the FS-ID for recoverable TS/TD has changed.
Parent topic: CASRB Error Messages


CASRB0060E Failed to open catalog. Return code = return-code

During the import of resource definitions, a bad return code was detected while trying to open the catalog.
System Action:
Import continues, but FCT entries that specifiy data set name will not be checked against the catalog.
Resolution:
Check that the file "catalog.dat" exists in the project folder, and that it is not open to another process.
Module:
dfhrdtup
Destination:
Build tab
Parent topic: CASRB0060 - CASRB0079


CASRB0070I Modified FCT entry FCT-name in group group-name, FS Server ID was "Old-FS-ID" now "New-FS-ID"

The FCT resource record was modified to bulk change the Fileshare server ID. The previous and new Fileshare server IDs are displayed.
System Action:
Update FCT entry.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0071I Processing FCT entries in group group-name, bulk update of Fileshare server (FS-ID)

Setting all FCT entries in the group to the specified Fileshare server ID.
System Action:
Process FCT entries.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0072I Group group-name not found

The specified group is not found in the RDT.
System Action:
Processing ends.
Resolution:
Correct the name for the requested group.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0073E Group group-name is invalid

The specified group name contains invalid characters.
System Action:
Processing ends.
Resolution:
Correct the name for the requested group.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0074E Resource definition path not specified

The resource definition path has not been specified on the command line.
System Action:
Processing ends.
Resolution:
Correct the command line.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0075E Options /s(sit-name,FS-ID) and /f(group-name,FS-ID) mutually exclusives

Both parameters /ssit-name and /f(group-name...) were requested but only one of them can be requested at a time.
System Action:
Processing ends.
Resolution:
Correct the command line and specify either /s or /f.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0076E SIT sit-name contains invalid characters

The name of the SIT contains invalid characters.
System Action:
Processing ends.
Resolution:
Correct the sit name.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0077E SIT sit-name not found

The name of the SIT does not exist.
System Action:
Processing ends.
Resolution:
Correct the sit name.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0078I Modified SIT sit-name. FS-ID for recoverable TS was old-recoverable-TS-name now new-recoverable-TS/TD-name.

The name of the FS-ID for recoverable TS/TD has changed.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRB0079I Modified SIT sit-name. FS-ID for recoverable TD was old-recoverable-TS-name now new-recoverable-TS/TD-name.

The name of the FS-ID for recoverable TS/TD has changed.
Module:
dfhpcupg
Destination:
Stdout
Parent topic: CASRB0060 - CASRB0079


CASRD Error Messages

  • CASRD0001 - CASRD0015
  • CASRD0016 - CASRD0030
  • CASRD0031 - CASRD0045
  • CASRD0046 - CASRD0052
  • CASRD1000 - CASRD1015
  • CASRD1016 - CASRD1041
Parent topic: Enterprise Server Error Messages


CASRD0001 - CASRD0015

  • CASRD0001E
    The resource-type entry resource-name is locked with an ENQ. Some other operation is currently being executed that involves it.
  • CASRD0002E
    The resource-type name resource-name is locked with an ENQ. Some other operation is currently being executed that involves it.
  • CASRD0003S
    ARRAY(0x2a9d620)
  • CASRD0004I
    Group group-name install is initiated from terminal or facility facility-id.
  • CASRD0005E
    Validation errors were found when preparing to install group group-name. The error messages are written to TS queue TS-queue-name. These messages may be reviewed with the utility transaction CEBR.
  • CASRD0006E
    Validation of group was successful but portions of the install failed for group group-name. The error messages are written to TS queue TS-queue-name. These messages may be reviewed with the utility transaction CEBR.
  • CASRD0007I
    The group group-name has been successfully installed. Details of the install are written to TD queue CRDI.
  • CASRD0008I
    The resource definition for resource-type entry resource-name from group group-name has replaced the previous definition in the current system.
  • CASRD0009I
    The resource definition for resource-type entry resource-name from group group-name is installed in the current system.
  • CASRD0010E
    The resource definition for resource-type entry resource-name from group group-name failed to install. The reason is reason-code. Reason codes are return codes.
  • CASRD0011S
    ARRAY(0x2886360)
  • CASRD0012W
    The resource type resource-type (resource resource-name, group group-name) is not supported.
  • CASRD0013W
    An attempt was made to delete the resource-type entry resource-namein preparation for re-installing it from group group-name. The delete failed with reason reason-code. Reason codes are return codes from the table manager. Common reasons are:
  • CASRD0014W
    An attempt was made to install the resource-type entry resource-name from group group-name after deleting the previous definition. The install failed with reason reason-code. Reason codes are return codes from the table manager. Common reasons are:
  • CASRD0015W
    The resource type resource-type (resource resource-name, group group-name) is not recognized.
Parent topic: CASRD Error Messages


CASRD0001E

The resource-type entry resource-name is locked with an ENQ. Some other operation is currently being executed that involves it.
System action:
The group group-name will be partially installed
Resolution:
Reinstall the group or resource.
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0001 - CASRD0015


CASRD0002E

The resource-type name resource-name is locked with an ENQ. Some other operation is currently being executed that involves it.
System action:
Validation continues but the group group-name will not be installed
Resolution:
Verify that the proper group is being installed and retry
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0001 - CASRD0015


CASRD0003S

ARRAY(0x2a9d620)
System action:
The request is rejected.
Resolution:
Verify that the proper group is being installed.
Destination:
terminal, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0001 - CASRD0015


CASRD0004I

Group group-name install is initiated from terminal or facility facility-id.
System action:
Continue operation
Resolution:
None
Destination:
console, TD queue CRDI
Module:
dfhzcins
Parent topic: CASRD0001 - CASRD0015


CASRD0005E

Validation errors were found when preparing to install group group-name. The error messages are written to TS queue TS-queue-name. These messages may be reviewed with the utility transaction CEBR.
System action:
The install request is rejected
Resolution:
Verify that the proper group is being installed, correct any errors noted in the detail messages in TS queue TS-queue-name.
Destination:
terminal, console, TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0001 - CASRD0015


CASRD0006E

Validation of group was successful but portions of the install failed for group group-name. The error messages are written to TS queue TS-queue-name. These messages may be reviewed with the utility transaction CEBR.
System action:
The install request was processed with errors
Resolution:
Review the detail error messages and take corrective action
Destination:
terminal, console, TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0001 - CASRD0015


CASRD0007I

The group group-name has been successfully installed. Details of the install are written to TD queue CRDI.
System action:
The install request is completed
Resolution:
None
Destination:
terminal, console, TD queue CRDI
Module:
dfhzcins
Parent topic: CASRD0001 - CASRD0015


CASRD0008I

The resource definition for resource-type entry resource-name from group group-name has replaced the previous definition in the current system.
System action:
Continue
Resolution:
None
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0001 - CASRD0015


CASRD0009I

The resource definition for resource-type entry resource-name from group group-name is installed in the current system.
System action:
Continue
Resolution:
None
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzins
Parent topic: CASRD0001 - CASRD0015


CASRD0010E

The resource definition for resource-type entry resource-name from group group-name failed to install. The reason is reason-code. Reason codes are return codes.
System action:
Continue, the current resource is not installed.
Resolution:
Review the group definition and the table manager return code and take appropriate corrective action.
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0001 - CASRD0015


CASRD0011S

ARRAY(0x2886360)
System action:
The request is rejected.
Resolution:
Verify the system installation. Check that the resource definition file has not been moved, deleted, or the network connection lost.
Destination:
terminal, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0001 - CASRD0015


CASRD0012W

The resource type resource-type (resource resource-name, group group-name) is not supported.
System action:
Continue
Resolution:
None
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0001 - CASRD0015


CASRD0013W

An attempt was made to delete the resource-type entry resource-namein preparation for re-installing it from group group-name. The delete failed with reason reason-code. Reason codes are return codes from the table manager. Common reasons are:
System action:
Continue
Resolution:
None
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0001 - CASRD0015


CASRD0014W

An attempt was made to install the resource-type entry resource-name from group group-name after deleting the previous definition. The install failed with reason reason-code. Reason codes are return codes from the table manager. Common reasons are:
System action:
Continue
Resolution:
None
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0001 - CASRD0015


CASRD0015W

The resource type resource-type (resource resource-name, group group-name) is not recognized.
System action:
Continue
Resolution:
None
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0001 - CASRD0015


CASRD0016 - CASRD0030

  • CASRD0016W
    The resource type resource-type (resource resource-name, group group-name) is not supported.
  • CASRD0017W
    The resource type resource-type (resource resource-name, group group-name) is not recognized.
  • CASRD0018E
    The resource definition for resource-type entry resource-name is not installable. The existing installed definition is in use.
  • CASRD0019E
    The resource definition for resource-type entry resource-name is not installable. The existing installed definition is in use.
  • CASRD0020E
    The resource definition for terminal resource-name is not installable. The existing installed definition is not replaceable.
  • CASRD0021E
    The resource definition for terminal resource-name is not installable. The existing installed definition is not replaceable.
  • CASRD0022E
    The resource definition for terminal resource-name is not installable. The existing installed definition is not replaceable.
  • CASRD0023E
    The resource definition for terminal resource-name is not installable. The existing installed definition is not replaceable.
  • CASRD0024E
    The resource definition for terminal resource-name is not installable. The existing installed definition is not recognized.
  • CASRD0025E
    The resource definition for resource-type entry resource-name is not installable. The existing installed definition is in use.
  • CASRD0026E
    The resource definition for resource-type entry resource-name is not installable. The existing installed definition is in use.
  • CASRD0027E
    ARRAY(0x2a9d458)
  • CASRD0028W
    The resource type resource-type (resource resource-name, group group-name) is not supported.
  • CASRD0029W
    The CVT resource type resource-type (resource resource-name, group group-name) is not supported.
  • CASRD0030E
    The resource-type entry resource-name is locked with an ENQ. Some other operation is currently being executed that involves it.
Parent topic: CASRD Error Messages


CASRD0016W

The resource type resource-type (resource resource-name, group group-name) is not supported.
System action:
Continue
Resolution:
None
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0016 - CASRD0030


CASRD0017W

The resource type resource-type (resource resource-name, group group-name) is not recognized.
System action:
Continue
Resolution:
None
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0016 - CASRD0030


CASRD0018E

The resource definition for resource-type entry resource-name is not installable. The existing installed definition is in use.
System action:
Continue, the group will not be installed.
Resolution:
Close and disable the file and retry the operation.
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0016 - CASRD0030


CASRD0019E

The resource definition for resource-type entry resource-name is not installable. The existing installed definition is in use.
System action:
Continue, the group will not be installed.
Resolution:
Close and disable the file and retry the operation.
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0016 - CASRD0030


CASRD0020E

The resource definition for terminal resource-name is not installable. The existing installed definition is not replaceable.
System action:
Continue, the group will not be installed.
Resolution:
None
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0016 - CASRD0030


CASRD0021E

The resource definition for terminal resource-name is not installable. The existing installed definition is not replaceable.
System action:
Continue, the group will not be installed.
Resolution:
None
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0016 - CASRD0030


CASRD0022E

The resource definition for terminal resource-name is not installable. The existing installed definition is not replaceable.
System action:
Continue, the group will not be installed.
Resolution:
None
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0016 - CASRD0030


CASRD0023E

The resource definition for terminal resource-name is not installable. The existing installed definition is not replaceable.
System action:
Continue, the group will not be installed.
Resolution:
None
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0016 - CASRD0030


CASRD0024E

The resource definition for terminal resource-name is not installable. The existing installed definition is not recognized.
System action:
Continue, the group will not be installed.
Resolution:
None
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0016 - CASRD0030


CASRD0025E

The resource definition for resource-type entry resource-name is not installable. The existing installed definition is in use.
System action:
Continue, the group will not be installed.
Resolution:
Close and disable the file and retry the operation.
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0016 - CASRD0030


CASRD0026E

The resource definition for resource-type entry resource-name is not installable. The existing installed definition is in use.
System action:
Continue, the group will not be installed.
Resolution:
Close and disable the file and retry the operation.
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0016 - CASRD0030


CASRD0027E

ARRAY(0x2a9d458)
System action:
The request is rejected.
Resolution:
Verify the system installation. Check that the CVT definition file has not been moved, deleted, or the network connection lost.
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0016 - CASRD0030


CASRD0028W

The resource type resource-type (resource resource-name, group group-name) is not supported.
System action:
Continue
Resolution:
None
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0016 - CASRD0030


CASRD0029W

The CVT resource type resource-type (resource resource-name, group group-name) is not supported.
System action:
Continue
Resolution:
None
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0016 - CASRD0030


CASRD0030E

The resource-type entry resource-name is locked with an ENQ. Some other operation is currently being executed that involves it.
System action:
Install continues but the CVT for resource-name is bypassed.
Resolution:
Verify that the proper group is being installed and retry
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0016 - CASRD0030


CASRD0031 - CASRD0045

  • CASRD0031I
    The CVT definition for resource-type entry resource-name from group group-name is installed in the current system.
  • CASRD0032E
    An attempt was made to install the resource-type entry resource-name from group group-name. The install failed with reason reason-code. Reason codes are return codes from the table manager. Common reasons are:
  • CASRD0033E
    An attempt was made to install the resource-type entry resource-name from group group-name. The install failed with error reason-code. Error codes are return codes from local storage allocation.
  • CASRD0034W
    An attempt was made to install the resource-type entry resource-name from group group-name. The table defined is ZERO length.
  • CASRD0035W
    An attempt was made to install the resource-type entry resource-name from group group-name. The base resource definition table was not found.
  • CASRD0036W
    During install of the resource-type entry resource-name, group group-name, a free main for the old table definition failed. The reason reason-code is the return from the free shared memory routine.
  • CASRD0037E
    A conversion table entry of type resource-type (entry resource-name, group group-name) is invalid.
  • CASRD0038E
    A conversion table entry of type resource-type (entry resource-name, group group-name) is not currently supported.
  • CASRD0039E
    Extra parameter or invalid parameter in install request for group group-name. The error or extra parameter is error-parameter.
  • CASRD0040E
    The resource type resource-type (resource resource-name, group group-name) is not found.
  • CASRD0041E
    The READ for resource type resource-type (resource resource-name, group group-name) failed for reason reason-code.
  • CASRD0042E
    The resource-type name resource-name is locked with an ENQ. Some other operation is currently being executed that involves it.
  • CASRD0043E
    The resource type that you are trying to install is not recognized.
  • CASRD0044E
    The GROUP keyword for the resource that you are trying to install is not recognized.
  • CASRD0045E
    The hexadecimal value entered for the transaction had a single quote missing or mismatched.
Parent topic: CASRD Error Messages


CASRD0031I

The CVT definition for resource-type entry resource-name from group group-name is installed in the current system.
System action:
Continue
Resolution:
None
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0031 - CASRD0045


CASRD0032E

An attempt was made to install the resource-type entry resource-name from group group-name. The install failed with reason reason-code. Reason codes are return codes from the table manager. Common reasons are:
System action:
Continue, the CVT definition is not installed.
Resolution:
None
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0031 - CASRD0045


CASRD0033E

An attempt was made to install the resource-type entry resource-name from group group-name. The install failed with error reason-code. Error codes are return codes from local storage allocation.
System action:
Continue, the CVT definition is not installed
Resolution:
None
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0031 - CASRD0045


CASRD0034W

An attempt was made to install the resource-type entry resource-name from group group-name. The table defined is ZERO length.
System action:
Continue, the CVT definition is not installed. If a definition was previously installed, it remains active.
Resolution:
None
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0031 - CASRD0045


CASRD0035W

An attempt was made to install the resource-type entry resource-name from group group-name. The base resource definition table was not found.
System action:
Continue, the CVT definition is not installed.
Resolution:
Install the base resource and than re-install this group.
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0031 - CASRD0045


CASRD0036W

During install of the resource-type entry resource-name, group group-name, a free main for the old table definition failed. The reason reason-code is the return from the free shared memory routine.
System action:
Continue
Resolution:
None
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0031 - CASRD0045


CASRD0037E

A conversion table entry of type resource-type (entry resource-name, group group-name) is invalid.
System action:
The entry is bypassed
Resolution:
Correct the definition
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0031 - CASRD0045


CASRD0038E

A conversion table entry of type resource-type (entry resource-name, group group-name) is not currently supported.
System action:
The entry is bypassed
Resolution:
Correct the definition
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0031 - CASRD0045


CASRD0039E

Extra parameter or invalid parameter in install request for group group-name. The error or extra parameter is error-parameter.
System action:
The request is not executed
Resolution:
Correct the request and resubmit
Destination:
terminal, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0031 - CASRD0045


CASRD0040E

The resource type resource-type (resource resource-name, group group-name) is not found.
System action:
The request is not executed
Resolution:
Correct the request and resubmit
Destination:
terminal, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0031 - CASRD0045


CASRD0041E

The READ for resource type resource-type (resource resource-name, group group-name) failed for reason reason-code.
System action:
The request is not executed
Resolution:
Check resource file (DFHDRDAT), correct the request and resubmit
Destination:
terminal, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0031 - CASRD0045


CASRD0042E

The resource-type name resource-name is locked with an ENQ. Some other operation is currently being executed that involves it.
System action:
The resource will not be installed
Resolution:
Verify that the proper resource is being installed and retry
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0031 - CASRD0045


CASRD0043E

The resource type that you are trying to install is not recognized.
System action:
The request is not executed
Resolution:
Correct the request and resubmit
Destination:
terminal, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0031 - CASRD0045


CASRD0044E

The GROUP keyword for the resource that you are trying to install is not recognized.
System action:
The request is not executed
Resolution:
Correct the request and resubmit
Destination:
terminal, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0031 - CASRD0045


CASRD0045E

The hexadecimal value entered for the transaction had a single quote missing or mismatched.
System action:
The request is not executed
Resolution:
Correct the request and resubmit
Destination:
terminal, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0031 - CASRD0045


CASRD0046 - CASRD0052

  • CASRD0046E
    The hexadecimal value entered for the transaction had a double quote missing or mismatched.
  • CASRD0047E
    The resource definition for resource-type entry resource-name is not installable. The existing installed definition is in use.
  • CASRD0048E
    The resource definition for resource-type entry resource-name is not installable. The existing installed definition is open.
  • CASRD0049E
    The resource definition for resource-type entry resource-name is not installable. The port port number is already in use.
  • CASRD0050E
    The URIMAP resource-name cannot be installed as it maps to the same HOST and PATH plus optional TCPIPSERVICE as URIMAP2.
  • CASRD0051E
    The DOCTEMPLATE resource-name cannot be installed as it contains the same TEMPLATENAME as DOCTEMPLATE2.
  • CASRD0052E
    The Current Userid Current Userid is not a surrogate of user URIMAP Userid or has not enough power the resource cannot be installed.
Parent topic: CASRD Error Messages


CASRD0046E

The hexadecimal value entered for the transaction had a double quote missing or mismatched.
System action:
The request is not executed
Resolution:
Correct the request and resubmit
Destination:
terminal, TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0046 - CASRD0052


CASRD0047E

The resource definition for resource-type entry resource-name is not installable. The existing installed definition is in use.
System action:
Continue, the resource will not be installed.
Resolution:
Disable the resource and retry the operation.
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0046 - CASRD0052


CASRD0048E

The resource definition for resource-type entry resource-name is not installable. The existing installed definition is open.
System action:
Continue, the resource will not be installed.
Resolution:
Close the service and retry the operation.
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0046 - CASRD0052


CASRD0049E

The resource definition for resource-type entry resource-name is not installable. The port port number is already in use.
System action:
Continue, the resource will not be installed.
Resolution:
Close the service using the port and retry the operation.
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0046 - CASRD0052


CASRD0050E

The URIMAP resource-name cannot be installed as it maps to the same HOST and PATH plus optional TCPIPSERVICE as URIMAP2.
System action:
Continue, the resource will not be installed.
Resolution:
Specify different HOST, PATH or TCPIPSERVICE values.
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0046 - CASRD0052


CASRD0051E

The DOCTEMPLATE resource-name cannot be installed as it contains the same TEMPLATENAME as DOCTEMPLATE2.
System action:
Continue, the resource will not be installed.
Resolution:
Specify different TEMPLATENAME values.
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0046 - CASRD0052


CASRD0052E

The Current Userid Current Userid is not a surrogate of user URIMAP Userid or has not enough power the resource cannot be installed.
System action:
Continue, the resource will not be installed.
Resolution:
Specify a different Userid or allow resource-type to be a surrogate.
Destination:
TS queue CEBR{facility-name}
Module:
dfhzcins
Parent topic: CASRD0046 - CASRD0052


CASRD1000 - CASRD1015

  • CASRD1000I
    The service was added successfully.
  • CASRD1001I
    The service was updated successfully.
  • CASRD1002I
    The service was deleted successfully.
  • CASRD1005E
    An unsuccessful request was made to add the named service. return-code values
  • CASRD1006E
    An unsuccessful request was made to update the named service. return-code values
  • CASRD1007E
    An unsuccessful request was made to delete the named service. return-code values
  • CASRD1008I
    An unrecognized administration request was made for the named service.
  • CASRD1010I
    The request handler was added successfully.
  • CASRD1011I
    The request handler was updated successfully.
  • CASRD1012I
    The request handler was deleted successfully.
  • CASRD1015E
    An unsuccessful request was made to add the named request handler. return-code values
Parent topic: CASRD Error Messages


CASRD1000I

The service was added successfully.
System action:
None.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1000 - CASRD1015


CASRD1001I

The service was updated successfully.
System action:
None.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1000 - CASRD1015


CASRD1002I

The service was deleted successfully.
System action:
None.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1000 - CASRD1015


CASRD1005E

An unsuccessful request was made to add the named service. return-code values
System action:
No updates made.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1000 - CASRD1015


CASRD1006E

An unsuccessful request was made to update the named service. return-code values
System action:
No updates made.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1000 - CASRD1015


CASRD1007E

An unsuccessful request was made to delete the named service. return-code values
System action:
No updates made.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1000 - CASRD1015


CASRD1008I

An unrecognized administration request was made for the named service.
System action:
Reject the request.
Resolution:
Check the product installation.
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1000 - CASRD1015


CASRD1010I

The request handler was added successfully.
System action:
None.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1000 - CASRD1015


CASRD1011I

The request handler was updated successfully.
System action:
None.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1000 - CASRD1015


CASRD1012I

The request handler was deleted successfully.
System action:
None.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1000 - CASRD1015


CASRD1015E

An unsuccessful request was made to add the named request handler. return-code values
System action:
No updates made.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1000 - CASRD1015


CASRD1016 - CASRD1041

  • CASRD1016E
    An unsuccessful request was made to update the named request handler. return-code values
  • CASRD1017E
    An unsuccessful request was made to delete the named request handler. return-code values
  • CASRD1018I
    An unrecognized administration request was made for the named request handler.
  • CASRD1030I
    The package was added successfully.
  • CASRD1031I
    The package was updated successfully.
  • CASRD1032I
    The package was deleted successfully.
  • CASRD1035E
    An unsuccessful request was made to add the named package. return-code values
  • CASRD1036E
    An unsuccessful request was made to update the named package. return-code values
  • CASRD1037E
    An unsuccessful request was made to delete the named package. return-code values
  • CASRD1038I
    An unrecognized administration request was made for the named package.
  • CASRD1039E
    A request to add, update or delete a service failed due to an unrecognised service definition.
  • CASRD1040E
    A request to add, update or delete a request handler failed due to an unrecognised request handler definition.
  • CASRD1041E
    A request to add, update or delete a package failed due to an unrecognised package definition.
Parent topic: CASRD Error Messages


CASRD1016E

An unsuccessful request was made to update the named request handler. return-code values
System action:
No updates made.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1016 - CASRD1041


CASRD1017E

An unsuccessful request was made to delete the named request handler. return-code values
System action:
No updates made.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1016 - CASRD1041


CASRD1018I

An unrecognized administration request was made for the named request handler.
System action:
Reject the request.
Resolution:
Check the product installation.
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1016 - CASRD1041


CASRD1030I

The package was added successfully.
System action:
None.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1016 - CASRD1041


CASRD1031I

The package was updated successfully.
System action:
None.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1016 - CASRD1041


CASRD1032I

The package was deleted successfully.
System action:
None.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1016 - CASRD1041


CASRD1035E

An unsuccessful request was made to add the named package. return-code values
System action:
No updates made.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1016 - CASRD1041


CASRD1036E

An unsuccessful request was made to update the named package. return-code values
System action:
No updates made.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1016 - CASRD1041


CASRD1037E

An unsuccessful request was made to delete the named package. return-code values
System action:
No updates made.
Resolution:
None
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1016 - CASRD1041


CASRD1038I

An unrecognized administration request was made for the named package.
System action:
Reject the request.
Resolution:
Check the product installation.
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1016 - CASRD1041


CASRD1039E

A request to add, update or delete a service failed due to an unrecognised service definition.
System action:
Reject the administration request.
Resolution:
Check the CAS components are compatible.
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1016 - CASRD1041


CASRD1040E

A request to add, update or delete a request handler failed due to an unrecognised request handler definition.
System action:
Reject the administration request.
Resolution:
Check the CAS components are compatible.
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1016 - CASRD1041


CASRD1041E

A request to add, update or delete a package failed due to an unrecognised package definition.
System action:
Reject the administration request.
Resolution:
Check the CAS components are compatible.
Destination:
Console
Module:
casasrvc
Parent topic: CASRD1016 - CASRD1041


CASRM Error Messages

  • 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.
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.
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.
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.
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.
System Action:
The ODBC resource manager will terminate abnormally.
Module:
dfhgodbc
Destination:
Console and standard error.
Parent topic: CASRM Error Messages


CASSE Error Messages

  • CASSE0000 - CASSE0019
  • CASSE0020 - CASSE0101
Parent topic: Enterprise Server Error Messages


CASSE0000 - CASSE0019

  • CASSE0000W Signon attempt at term-id, for user user-id unsuccessful.
    user-id is either not recognized or did not specify a correct password.
  • CASSE0001E Security violation. Terminal term-id, transaction trans-id, user user-id.
    user-id is not authorized to access transaction trans-id.
  • CASSE0002I Signon complete at term-id, for user user-id.
    user-id has successfully completed signon at terminal term-id.
  • CASSE0003I Signon complete at term-id, for user user-id. Password changed.
    user-id has successfully completed signon at terminal term-id. The password for user-id has been changed.
  • CASSE0004I Signon complete at term-id, for user user-id. Password unchanged.
    user-id has successfully completed signon at terminal term-id. The password for user-id has not been changed because the second entry of the new password did not match the first entry.
  • CASSE0005W SIGNON fail. Terminal term-id, TranId trans-id, Program program-id, User user-id.
    The program program-id, executing as part of the trans-id transaction, attempted to signon user user-id at terminal term-id, but user-id is either not recognized or an incorrect password was specified.
  • CASSE0006I Sign-Off complete
    The user is signed off the current device or terminal.
  • CASSE0007I Security is disabled
    The resource definition file used to start this region had security set to none.
  • CASSE0008I Region is running with Resource security enabled.
    The resource definition file used by this region has resource security enabled.
  • CASSE0009I Region is running with Resource security disabled.
    The resource definition file used by this region has resource security disabled.
  • CASSE0010I Region is running with Resource security enabled.
    The resource definition file used by this region has resource security enabled.
  • CASSE0011I Region is running with Resource security disabled.
    The resource definition file used by this region has resource security disabled.
  • CASSE0012I Signon complete at term-id, for user user-id. Local security is disabled.
    user-id has successfully completed signon at terminal term-id, but local security has been disabled.
  • CASSE0013I Signon complete at term-id, for user user-id. Password changed. Local security is disabled.
    user-id has successfully completed signon at terminal term-id. The password for user-id has been changed, but local security has been disabled.
  • CASSE0014I Signon complete at term-id, for user user-id. Password unchanged. Local security is disabled.
    user-id has successfully completed signon at terminal term-id. The password for user-id has not been changed because the second entry of the new password did not match the first entry. Local security has been disabled.
  • CASSE0015W Signon attempt at term-id, for user user-id unsuccessful.
    user-id is either not recognized or did not specify a correct password.
  • CASSE0016I Signon complete at term-id, for user user-id.
    user-id has successfully completed signon at terminal term-id.
  • CASSE0017I Signon cancelled at user request
    The signon request was cancelled.
  • CASSE0018I Signon complete at term-id, for user user-id using saved userid/password. (Use "CESG CLEAR" to re-signon)
    user-id has successfully completed signon at terminal term-id using a userid/password which was saved during a previous signon request. Use "CESG CLEAR" to remove saved userid/password.
  • CASSE0019W Unexpected signon failure
    An expected error occured processing the signon request. The security daemon may not be present or functioning correctly.
Parent topic: CASSE Error Messages


CASSE0000W Signon attempt at term-id, for user user-id unsuccessful.

user-id is either not recognized or did not specify a correct password.
System Action:
The signon attempt is rejected.
Resolution:
Supply both a correct user-id and correct password.
Module:
dfhzcesn
Destination:
User terminal, console, and TDQ CSCS
Parent topic: CASSE0000 - CASSE0019


CASSE0001E Security violation. Terminal term-id, transaction trans-id, user user-id.

user-id is not authorized to access transaction trans-id.
System Action:
The transaction request is rejected.
Resolution:
Ask the security administrator to verify the permissions associated with transaction trans-id.
Module:
dfheserv
Destination:
User terminal
Parent topic: CASSE0000 - CASSE0019


CASSE0002I Signon complete at term-id, for user user-id.

user-id has successfully completed signon at terminal term-id.
System Action:
%2$s access authority is granted at terminal %1$s.
Resolution:
None.
Module:
dfhzcesn
Destination:
User terminal and TDQ CSCS
Parent topic: CASSE0000 - CASSE0019


CASSE0003I Signon complete at term-id, for user user-id. Password changed.

user-id has successfully completed signon at terminal term-id. The password for user-id has been changed.
System Action:
%2$s access authority is granted at terminal %1$s and the password has been changed for %2$s.
Resolution:
None.
Module:
dfhzcesn
Destination:
User terminal and TDQ CSCS
Parent topic: CASSE0000 - CASSE0019


CASSE0004I Signon complete at term-id, for user user-id. Password unchanged.

user-id has successfully completed signon at terminal term-id. The password for user-id has not been changed because the second entry of the new password did not match the first entry.
System Action:
%2$s access authority is granted at terminal %1$s.
Resolution:
Re-enter the CESN transaction and signon again requesting a new password. Be careful to enter the new password the second time exactly as the new password was entered the first time.
Module:
dfhzcesn
Destination:
User terminal and TDQ CSCS
Parent topic: CASSE0000 - CASSE0019


CASSE0005W SIGNON fail. Terminal term-id, TranId trans-id, Program program-id, User user-id.

The program program-id, executing as part of the trans-id transaction, attempted to signon user user-id at terminal term-id, but user-id is either not recognized or an incorrect password was specified.
System Action:
The SIGNON request is rejected.
Resolution:
For Tranid = CESN and Program = dfhzcesn, this should be a duplicate of TXSE0000W and handled identically. Otherwise, the message indicates a user error with the specified program or an error in the specified program's logic.
Module:
dfheexin
Destination:
Console and TDQ CSCS
Parent topic: CASSE0000 - CASSE0019


CASSE0006I Sign-Off complete

The user is signed off the current device or terminal.
System Action:
None.
Resolution:
None.
Module:
dfhzcesn
Destination:
User terminal
Parent topic: CASSE0000 - CASSE0019


CASSE0007I Security is disabled

The resource definition file used to start this region had security set to none.
System Action:
No resource level security checking will be done.
Resolution:
None.
Module:
dfhzcesn
Destination:
User terminal
Parent topic: CASSE0000 - CASSE0019


CASSE0008I Region is running with Resource security enabled.

The resource definition file used by this region has resource security enabled.
System Action:
All security features are enabled.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSE0000 - CASSE0019


CASSE0009I Region is running with Resource security disabled.

The resource definition file used by this region has resource security disabled.
System Action:
All security features are disabled.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSE0000 - CASSE0019


CASSE0010I Region is running with Resource security enabled.

The resource definition file used by this region has resource security enabled.
System Action:
All security features are enabled.
Module:
dfhginit
Destination:
Console and standard error
Parent topic: CASSE0000 - CASSE0019


CASSE0011I Region is running with Resource security disabled.

The resource definition file used by this region has resource security disabled.
System Action:
All security features are disabled.
Module:
dfhginit
Destination:
Console and standard error
Parent topic: CASSE0000 - CASSE0019


CASSE0012I Signon complete at term-id, for user user-id. Local security is disabled.

user-id has successfully completed signon at terminal term-id, but local security has been disabled.
System Action:
%2$s access authority is granted at terminal %1$s.
Resolution:
None.
Module:
dfhzcesn
Destination:
User terminal and TDQ CSCS
Parent topic: CASSE0000 - CASSE0019


CASSE0013I Signon complete at term-id, for user user-id. Password changed. Local security is disabled.

user-id has successfully completed signon at terminal term-id. The password for user-id has been changed, but local security has been disabled.
System Action:
%2$s access authority is granted at terminal %1$s and the password has been changed for %2$s.
Resolution:
None.
Module:
dfhzcesn
Destination:
User terminal and TDQ CSCS
Parent topic: CASSE0000 - CASSE0019


CASSE0014I Signon complete at term-id, for user user-id. Password unchanged. Local security is disabled.

user-id has successfully completed signon at terminal term-id. The password for user-id has not been changed because the second entry of the new password did not match the first entry. Local security has been disabled.
System Action:
%2$s access authority is granted at terminal %1$s.
Resolution:
Re-enter the CESN transaction and signon again requesting a new password. Be careful to enter the new password the second time exactly as the new password was entered the first time.
Module:
dfhzcesn
Destination:
User terminal and TDQ CSCS
Parent topic: CASSE0000 - CASSE0019


CASSE0015W Signon attempt at term-id, for user user-id unsuccessful.

user-id is either not recognized or did not specify a correct password.
System Action:
The signon attempt is rejected.
Resolution:
Supply both a correct user-id and correct password.
Module:
dfhzcesg
Destination:
User terminal, console and TDQ CSCS
Parent topic: CASSE0000 - CASSE0019


CASSE0016I Signon complete at term-id, for user user-id.

user-id has successfully completed signon at terminal term-id.
System Action:
%2$s access authority is granted at terminal %1$s.
Resolution:
None.
Module:
dfhzcesg
Destination:
User terminal and TDQ CSCS
Parent topic: CASSE0000 - CASSE0019


CASSE0017I Signon cancelled at user request

The signon request was cancelled.
System Action:
No CICS signon will be attempted.
Resolution:
None.
Module:
dfhzcesg
Destination:
User terminal.
Parent topic: CASSE0000 - CASSE0019


CASSE0018I Signon complete at term-id, for user user-id using saved userid/password. (Use "CESG CLEAR" to re-signon)

user-id has successfully completed signon at terminal term-id using a userid/password which was saved during a previous signon request. Use "CESG CLEAR" to remove saved userid/password.
System Action:
%2$s access authority is granted at terminal %1$s.
Resolution:
None.
Module:
dfhzcesg
Destination:
User terminal and TDQ CSCS
Parent topic: CASSE0000 - CASSE0019


CASSE0019W Unexpected signon failure

An expected error occured processing the signon request. The security daemon may not be present or functioning correctly.
System Action:
The signon attempt is rejected.
Resolution:
Try again or use the CESN transaction if problems persists.
Module:
dfhzcesg
Destination:
User terminal, console and TDQ CSCS
Parent topic: CASSE0000 - CASSE0019


CASSE0020 - CASSE0101

  • CASSE0020W Sign-off option must be LOGOFF or GOODNIGHT. Sign-off is ignored.
    The only option that may be passed to the sign-off transaction is LOGOFF or GOODNIGHT.
  • CASSE0021W SIGNON fail. Terminal term-id, TranId trans-id, Program program-id, User user-id, ESMRESP esm-resp, ESMREASON esm-reason.
    The program program-id, executing as part of the trans-id transaction, attempted to signon user user-id at terminal term-id, but user-id is either not recognized or an incorrect password was specified.
  • CASSE0030I External security exit enabled: SNT(SNT-exit-enabled), RSL(RSL-exit-enabled), Sign-on(Sign-on-exit-enabled), VerifyPWD(Verify-Password-exit-enabled).
    The external security user exit has been enabled.
  • CASSE0031W Signon failed. User already signed on at terminal term-id.
    The user is already signed on at terminal term-id and single signon is being enforced for CICS terminals.
  • CASSE0032E User ID "" invalid or password incorrect, region terminating
    The associated user ID was invalid or the supplied password was incorrect.
  • CASSE0033E User not authorized to start ES "", region terminating.
    The supplied user has not the credentials to start ES.
  • CASSE0034E PLTPI user "" invalid, region terminating.
    The supplied PLTPI user is invalid.
  • CASSE0035E User "" is not a surrogate user of PLTPI user "", region terminating.
    The supplied user has not the credentials to run PLTPI processing.
  • CASSE0036E User ID "" invalid or password incorrect.
    The associated user ID was invalid or the supplied password was incorrect.
  • CASSE0037I User "" deleted SNT entry "".
    The SNT entry has been deleted in ESMAC by user.
  • CASSE0038I User "" modified SNT entry "".
    The SNT entry has been modified in ESMAC by user.
  • CASSE0050I Success-message
    The ESF update request was successful.
  • CASSE0051E Error-message
    The ESF update request was unsuccessful.
  • CASSE0101E Security violation. Terminal term-id, resource trans-id, user user-id, code return code, reason reason code.
    user-id is not authorized to access resource trans-id. Return and reason codes are similar to RACF.
Parent topic: CASSE Error Messages


CASSE0020W Sign-off option must be LOGOFF or GOODNIGHT. Sign-off is ignored.

The only option that may be passed to the sign-off transaction is LOGOFF or GOODNIGHT.
System Action:
The sign-off attempt is rejected.
Resolution:
Try again with a valid or no option.
Module:
dfhzcesn
Destination:
User terminal
Parent topic: CASSE0020 - CASSE0101


CASSE0021W SIGNON fail. Terminal term-id, TranId trans-id, Program program-id, User user-id, ESMRESP esm-resp, ESMREASON esm-reason.

The program program-id, executing as part of the trans-id transaction, attempted to signon user user-id at terminal term-id, but user-id is either not recognized or an incorrect password was specified.
System Action:
The SIGNON request is rejected.
Resolution:
For Tranid = CESN and Program = dfhzcesn, this should be a duplicate of TXSE0000W and handled identically. Otherwise, the message indicates a user error with the specified program or an error in the specified program's logic.
Module:
dfheexin
Destination:
Console and TDQ CSCS
Parent topic: CASSE0020 - CASSE0101


CASSE0030I External security exit enabled: SNT(SNT-exit-enabled), RSL(RSL-exit-enabled), Sign-on(Sign-on-exit-enabled), VerifyPWD(Verify-Password-exit-enabled).

The external security user exit has been enabled.
  • SNT(Y) - User information within ES configuration will be ignored.
  • RSL(Y) - User exit will perform authorization for RSL enabled transactions.
  • Sign-on(Y) - User exit will perform authentication.
  • VerifyPWD(Y) - User exit will perform verify password functionality.
System Action:
Any options set to N will assume default behaviour.
Module:
dfheexin
Destination:
Console
Parent topic: CASSE0020 - CASSE0101


CASSE0031W Signon failed. User already signed on at terminal term-id.

The user is already signed on at terminal term-id and single signon is being enforced for CICS terminals.
System Action:
The signon attempt is rejected.
Resolution:
Signoff terminal term-id and retry the operation.
Module:
dfhzcesn
Destination:
User terminal and TDQ CSCS
Parent topic: CASSE0020 - CASSE0101


CASSE0032E User ID "" invalid or password incorrect, region terminating

The associated user ID was invalid or the supplied password was incorrect.
System Action:
The region is terminated immediately.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASSE0020 - CASSE0101


CASSE0033E User not authorized to start ES "", region terminating.

The supplied user has not the credentials to start ES.
System Action:
The region is terminated immediately.
Resolution:
Correct the user or the credentials such that he can start the region.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASSE0020 - CASSE0101


CASSE0034E PLTPI user "" invalid, region terminating.

The supplied PLTPI user is invalid.
System Action:
The region is terminated immediately.
Resolution:
Correct the user for the PLTPI processing and restart the region.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASSE0020 - CASSE0101


CASSE0035E User "" is not a surrogate user of PLTPI user "", region terminating.

The supplied user has not the credentials to run PLTPI processing.
System Action:
The region is terminated immediately.
Resolution:
Correct the user or the credentials such that he can start the region.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASSE0020 - CASSE0101


CASSE0036E User ID "" invalid or password incorrect.

The associated user ID was invalid or the supplied password was incorrect.
System Action:
User signon is rejected.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASSE0020 - CASSE0101


CASSE0037I User "" deleted SNT entry "".

The SNT entry has been deleted in ESMAC by user.
System Action:
None.
Module:
casrdo93
Destination:
CSCS TDQ.
Parent topic: CASSE0020 - CASSE0101


CASSE0038I User "" modified SNT entry "".

The SNT entry has been modified in ESMAC by user.
System Action:
None.
Module:
casrdo93
Destination:
CSCS TDQ.
Parent topic: CASSE0020 - CASSE0101


CASSE0050I Success-message

The ESF update request was successful.
System Action:
ESF update processed.
Module:
casaesfu
Destination:
System Console
Parent topic: CASSE0020 - CASSE0101


CASSE0051E Error-message

The ESF update request was unsuccessful.
System Action:
ESF update rejected.
Module:
casaesfu
Destination:
System Console
Parent topic: CASSE0020 - CASSE0101


CASSE0101E Security violation. Terminal term-id, resource trans-id, user user-id, code return code, reason reason code.

user-id is not authorized to access resource trans-id. Return and reason codes are similar to RACF.

Values for code and their meaning are:

04
not protected
08
not authorized
20
access violation (see meaning)
24
unspecified error

Values for reason and their meaning are:

00
not authorized
04
read access attempted
08
update access attempted
12
control access attempted
16
alter access attempted
44
not authorized
System Action:
The request is rejected.
Resolution:
Ask the security administrator to verify the permissions associated with resource trans-id.
Module:
dfheserv
Destination:
TDQ CSCS
Parent topic: CASSE0020 - CASSE0101


CASSI Error Messages

  • CASSI0000 - CASSI0013
  • CASSI1000 - CASSI1015
  • CASSI1400 - CASSI1415
  • CASSI1416 - CASSI1600
  • CASSI1700 - CASSI1715
  • CASSI1716 - CASSI1730
  • CASSI1731 - CASSI1747
  • CASSI1800 - CASSI1900
  • CASSI2000 - CASSI2152
  • CASSI2201 - CASSI4005
  • CASSI5000 - CASSI5040
  • CASSI6000 - CASSI8005
  • CASSI9001 - CASSI9025
Parent topic: Enterprise Server Error Messages


CASSI0000 - CASSI0013

  • CASSI0000I
    A region has started its initialization phase
  • CASSI0001I
    In the region manager's initialization phase the SIT has been read and the region will use the SYSID specified in that SIT.
  • CASSI0002F
    In the region manager's initialization phase the shared memory creation failed.
  • CASSI0003F
    In the region manager's initialization phase the semaphore creation failed.
  • CASSI0004S
    The Program Load Table Pre-Initialization (PLTPI) list PLTPI-list-namewhich was specified in the SIT for the starting region could not be located in any of the groups installed to the system.
  • CASSI0005S
    An attempt to start a region with a specified SIT SIT-name was unsuccessful as the SIT was not found in the resource definition file.
  • CASSI0006S
    Whilst attempting to open the resource definition file an error occurred. If fcd-stat-byte-1 is '9' then fcd-stat-byte-2 will contain the COBOL run-time error code.
  • CASSI0007S
    An error occurred whilst closing the resource definition file.
  • CASSI0008W
    After successfully creating and attaching to the shared memory a re-attach call failed.
  • CASSI0009S
    An error occured when attempting to register the storage of the specified type using the AMODE selected in the SIT.
  • CASSI0010S
    An error occured when attempting to register the storage of the specified type using the AMODE selected in the SIT.
  • CASSI0011I
    An external security manager is configured for the region therefore external shutdown of the region will require sign on.
  • CASSI0012I
    The region bitism mode
  • CASSI0013W
    The OS refused the memory allocation request, which included the configured Extended User Storage Area.
Parent topic: CASSI Error Messages


CASSI0000I

A region has started its initialization phase
System action:
Resolution:
None.
Destination:
Console and standard error.
Module:
dfhginit
Parent topic: CASSI0000 - CASSI0013


CASSI0001I

In the region manager's initialization phase the SIT has been read and the region will use the SYSID specified in that SIT.
System action:
Resolution:
None.
Destination:
Console and standard error.
Module:
dfhginit
Parent topic: CASSI0000 - CASSI0013


CASSI0002F

In the region manager's initialization phase the shared memory creation failed.
System action:
As a region cannot run without a shared memory pool the region manager will stop.
Resolution:
None.
Destination:
Console and standard error.
Module:
dfhginit
Parent topic: CASSI0000 - CASSI0013


CASSI0003F

In the region manager's initialization phase the semaphore creation failed.
System action:
As shared memory can not be protected without the semaphore the region manager will stop.
Resolution:
None.
Destination:
Console and standard error.
Module:
dfhginit
Parent topic: CASSI0000 - CASSI0013


CASSI0004S

The Program Load Table Pre-Initialization (PLTPI) list PLTPI-list-namewhich was specified in the SIT for the starting region could not be located in any of the groups installed to the system.
System action:
The region will not be started.
Resolution:
Make sure that the PLTPI list specified in the SIT is defined in a group which is installed to the system on system initialization. The list of groups to be installed to the system is defined in the startup list resource definition record.
Destination:
Console and standard error.
Module:
dfhginit
Parent topic: CASSI0000 - CASSI0013


CASSI0005S

An attempt to start a region with a specified SIT SIT-name was unsuccessful as the SIT was not found in the resource definition file.
System action:
The region will not be started.
Resolution:
Make sure that the SIT is defined in the region's resource definitions. If the record does not exist then either request that the system administrator create the required SIT or use another one.
Destination:
Console and standard error.
Module:
dfhginit
Parent topic: CASSI0000 - CASSI0013


CASSI0006S

Whilst attempting to open the resource definition file an error occurred. If fcd-stat-byte-1 is '9' then fcd-stat-byte-2 will contain the COBOL run-time error code.
System action:
As the system cannot read the resource definitions the region manager will stop.
Resolution:
None.
Destination:
Console and standard error.
Module:
dfhginit
Parent topic: CASSI0000 - CASSI0013


CASSI0007S

An error occurred whilst closing the resource definition file.
System action:
None.
Resolution:
None.
Destination:
Console and standard error.
Module:
dfhginit
Parent topic: CASSI0000 - CASSI0013


CASSI0008W

After successfully creating and attaching to the shared memory a re-attach call failed.
System action:
The system will continue to operate normally, but animation of local ECI clients will fail.
Resolution:
None.
Destination:
Console and standard error.
Module:
dfhginit
Parent topic: CASSI0000 - CASSI0013


CASSI0009S

An error occured when attempting to register the storage of the specified type using the AMODE selected in the SIT.
System action:
The region will not be started.
Resolution:
Verify the settings for AMODE and number of shared pages in the SIT.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI0000 - CASSI0013


CASSI0010S

An error occured when attempting to register the storage of the specified type using the AMODE selected in the SIT.
System action:
The region will not be started.
Resolution:
Verify the settings for AMODE and number of shared pages in the SIT.
Destination:
Console and standard error.
Module:
dfheserv
Parent topic: CASSI0000 - CASSI0013


CASSI0011I

An external security manager is configured for the region therefore external shutdown of the region will require sign on.
System action:
None.
Resolution:
None.
Destination:
Console and standard error.
Module:
dfhginit
Parent topic: CASSI0000 - CASSI0013


CASSI0012I

The region bitism mode
System action:
None.
Resolution:
None.
Destination:
Console and standard error.
Module:
dfhginit
Parent topic: CASSI0000 - CASSI0013


CASSI0013W

The OS refused the memory allocation request, which included the configured Extended User Storage Area.
System action:
The system will continue to operate normally, but no large GETMAIN SHARED allocations will be possible.
Resolution:
Reduce the amount of memory allocated by the ES_EUSA_SIZE environment variable.
Destination:
Console and standard error.
Module:
dfhginit
Parent topic: CASSI0000 - CASSI0013


CASSI1000 - CASSI1015

  • CASSI1000I
    The region manager has successfully completed its initialization phase.
  • CASSI1001S
    The region manager failed during its initialization phase.
  • CASSI1002S
    The region manager failed the license check during its initialization phase.
  • CASSI1003W
    The region manager failed the CICS license check during its initialization phase.
  • CASSI1004W
    The requested number of licenses were not available at initialization.
  • CASSI1005E
    An error occurred requesting additional licenses.
  • CASSI1006E
    An error occurred returning licenses.
  • CASSI1007E
    An error occurred requesting licenses from CES but the length of the text of the message cannot be retrieved from CES.
  • CASSI1008E
    An error occurred requesting licenses from CES but the text of the message cannot be retrieved from CES.
  • CASSI1009E
    An error occurred requesting licenses from CES.
  • CASSI1010W Error environment variable ES_CERTIFICATES_LOCATION not set or pointing to an invalid location
    An error occurred because either the environment variable is not set is pointing to an invalid location.
  • CASSI1011W TCPIPSERVICE TCPIPSERVICE name could not be started. Certificate Certificate name could not be found
    The TCPIPSERVICE could not be started because the specified certificate could not be found.
  • CASSI1012W Error no certificate specified for TCPIPSERVICE TCPIPSERVICE name and ES_DFLT_CERTIFICATE_NAME_SERVER not set
    The TCPIPSERVICE could not be started because a name was not provided for the certificate and ES_DFLT_CERTIFICATE_NAME_SERVER was not set.
  • CASSI1013W Error TCPIPSERVICE TCPIPSERVICE name could not be started. No passphrase for server certificate Certificate name
    The TCPIPSERVICE is using a certificate and either the user exit ESCERTPAS could not be found or the user exit did not return a passphrase.
  • CASSI1014W No CA root file provided to validate client certificates for TCPIPSERVICE TCPIPSERVICE name. Server certificate is Certificate name
    The TCPIPSERVICE is using a server certificate, but either the user exit ESCERTPAS could not be found or the user exit did not return a CA root file.
  • CASSI1015W TCPIPSERVICE TCPIPSERVICE name could not be started. Keyfile Keyfile name could not be found
    The TCPIPSERVICE could not be started because the keyfile could not be found.
Parent topic: CASSI Error Messages


CASSI1000I

The region manager has successfully completed its initialization phase.
System action:
None.
Resolution:
None.
Destination:
Console and standard error.
Module:
dfhgglbl
Parent topic: CASSI1000 - CASSI1015


CASSI1001S

The region manager failed during its initialization phase.
System action:
None.
Resolution:
None.
Destination:
Console and standard error.
Module:
dfhgglbl
Parent topic: CASSI1000 - CASSI1015


CASSI1002S

The region manager failed the license check during its initialization phase.
System action:
None.
Resolution:
None.
Destination:
Console and standard error.
Module:
dfhgglbl
Parent topic: CASSI1000 - CASSI1015


CASSI1003W

The region manager failed the CICS license check during its initialization phase.
System action:
None.
Resolution:
None.
Destination:
Console and standard error.
Module:
dfhgglbl
Parent topic: CASSI1000 - CASSI1015


CASSI1004W

The requested number of licenses were not available at initialization.
System action:
The server will continue with the reduced number of license units.
Resolution:
None.
Destination:
Console and standard error.
Module:
dfhgglbl
Parent topic: CASSI1000 - CASSI1015


CASSI1005E

An error occurred requesting additional licenses.
System action:
No new licenses will be allocated.
Resolution:
Check that the licensing software is installed and configured correctly.
Destination:
Console and standard error.
Module:
dfhgglbl
Parent topic: CASSI1000 - CASSI1015


CASSI1006E

An error occurred returning licenses.
System action:
Licenses will not be returned.
Resolution:
Check that the licensing software is installed and configured correctly.
Destination:
Console and standard error.
Module:
dfhgglbl
Parent topic: CASSI1000 - CASSI1015


CASSI1007E

An error occurred requesting licenses from CES but the length of the text of the message cannot be retrieved from CES.
System action:
Licenses will not be obtained.
Resolution:
Check that the licensing software is installed and configured correctly.
Destination:
Console and standard error.
Module:
dfhgglbl
Parent topic: CASSI1000 - CASSI1015


CASSI1008E

An error occurred requesting licenses from CES but the text of the message cannot be retrieved from CES.
System action:
Licenses will not be obtained.
Resolution:
Check that the licensing software is installed and configured correctly.
Destination:
Console and standard error.
Module:
dfhgglbl
Parent topic: CASSI1000 - CASSI1015


CASSI1009E

An error occurred requesting licenses from CES.
System action:
Licenses will not be obtained.
Resolution:
Check that the licensing software is installed and configured correctly.
Destination:
Console and standard error.
Module:
dfhgglbl
Parent topic: CASSI1000 - CASSI1015


CASSI1010W Error environment variable ES_CERTIFICATES_LOCATION not set or pointing to an invalid location

An error occurred because either the environment variable is not set is pointing to an invalid location.
System Action:
SSL listener will not be started.
Resolution:
Check that the environment variable is valid and points to the location of your server certificates.
Module:
casmgr/dfhzcins
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1015


CASSI1011W TCPIPSERVICE TCPIPSERVICE name could not be started. Certificate Certificate name could not be found

The TCPIPSERVICE could not be started because the specified certificate could not be found.
System Action:
SSL listener will not be started.
Resolution:
Check your configuration.
Module:
casmgr/dfhzcins
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1015


CASSI1012W Error no certificate specified for TCPIPSERVICE TCPIPSERVICE name and ES_DFLT_CERTIFICATE_NAME_SERVER not set

The TCPIPSERVICE could not be started because a name was not provided for the certificate and ES_DFLT_CERTIFICATE_NAME_SERVER was not set.
System Action:
SSL listener will not be started.
Resolution:
Check your configuration, or add a name to the certificate field for the TCPIPSERVICE.
Module:
casmgr/dfhzcins
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1015


CASSI1013W Error TCPIPSERVICE TCPIPSERVICE name could not be started. No passphrase for server certificate Certificate name

The TCPIPSERVICE is using a certificate and either the user exit ESCERTPAS could not be found or the user exit did not return a passphrase.
System Action:
SSL listener will not be started.
Resolution:
Check your configuration and ensure that the user exit ESCERTPAS is found and returns a correct passphrase for the certificate in use.
Module:
casmgr/dfhzcins
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1015


CASSI1014W No CA root file provided to validate client certificates for TCPIPSERVICE TCPIPSERVICE name. Server certificate is Certificate name

The TCPIPSERVICE is using a server certificate, but either the user exit ESCERTPAS could not be found or the user exit did not return a CA root file.
Resolution:
Check your configuration and ensure that the user exit ESCERTPAS is found and returns a correct CA root for any clients that may use this TCPIPSERVICE.
Module:
casmgr/dfhzcins
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1015


CASSI1015W TCPIPSERVICE TCPIPSERVICE name could not be started. Keyfile Keyfile name could not be found

The TCPIPSERVICE could not be started because the keyfile could not be found.
System Action:
SSL listener will not be started.
Resolution:
Check your configuration.
Module:
casmgr/dfhzcins
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1015


CASSI1400 - CASSI1415

  • CASSI1400S
    The name of the temporary storage/transient data file as specified in the SIT is illegal.
  • CASSI1401S
    While attempting to initialize the temporary storage or transient data file an error occurred while connecting with the Fileshare server FS-server.
  • CASSI1402S
    While attempting to initialize the temporary storage or transient data file a run time error occurred.
  • CASSI1403S
    While attempting to initialize the temporary storage or transient data file a file access error occurred.
  • CASSI1404S
    While attempting to locate the temporary storage or transient data file an error occurred.
  • CASSI1410S
    The attempt to start a CICS API server under animator control failed due to an error in DosExecPgm.
  • CASSI1411E
    The attempt to inform the region manager of the animate server's termination failed due to an error in DosExecPgm.
  • CASSI1412S
    The attempt to start a CICS API server under animator control failed due to an error in execlp.
  • CASSI1413S
    The attempt to start a CICS API server under animator control failed due to $COBDIR\cli.lbr not being found.
  • CASSI1414S
    The attempt to start a CICS API server under animator control failed due to $COBDIR\cobcli.lbr not being found.
  • CASSI1415E
    An error occurred loading dfheini1. Either the module dfheini1.gnt is not in $CASDIR/lib or the environment variable CASDIR is not properly set.
Parent topic: CASSI Error Messages


CASSI1400S

The name of the temporary storage/transient data file as specified in the SIT is illegal.

The temporary storage/transient data file names are as follows:

TXTSNR
Temporary storage non-recoverable.
TXTSRC
Temporary storage recoverable.
TXTDNR
Transient data non-recoverable.
TXTDRC
Transient data recoverable.
System action:
The system file can not be opened successfully so the region initialization will be unsuccessful.
Resolution:
Correct the name given in the SIT, making sure that no filename is given, only the path and that the directory exists.
Destination:
Console and standard error
Module:
dfheini1(dfhcptdi)
Parent topic: CASSI1400 - CASSI1415


CASSI1401S

While attempting to initialize the temporary storage or transient data file an error occurred while connecting with the Fileshare server FS-server.
System action:
The system file can not be opened successfully so the region initialization will be unsuccessful.
Resolution:
Make sure that the Fileshare server FS-server is running or correct the name given in the SIT.
Destination:
Console
Module:
dfheini1(dfhcptdi)
Parent topic: CASSI1400 - CASSI1415


CASSI1402S

While attempting to initialize the temporary storage or transient data file a run time error occurred.
System action:
The system file can not be opened successfully so the region initialization will be unsuccessful.
Resolution:
Correct the run time error and retry.
Destination:
Console
Module:
dfheini1(dfhcptdi)
Parent topic: CASSI1400 - CASSI1415


CASSI1403S

While attempting to initialize the temporary storage or transient data file a file access error occurred.
System action:
The system file can not be opened successfully so the region initialization will be unsuccessful.
Resolution:
Look up the file status codes and correct the error.
Destination:
Console and standard error
Module:
dfheini1(dfhcptdi)
Parent topic: CASSI1400 - CASSI1415


CASSI1404S

While attempting to locate the temporary storage or transient data file an error occurred.
System action:
The system file can not be opened successfully so the region initialization will be unsuccessful.
Resolution:
Look up the status code for the FS_LOCATE_FILE file call, correct the error specified and re-try.
Destination:
Console and standard error
Module:
dfheini1(dfhcptdi)
Parent topic: CASSI1400 - CASSI1415


CASSI1410S

The attempt to start a CICS API server under animator control failed due to an error in DosExecPgm.
System action:
The animate server cannot be started so the process will terminate.
Resolution:
None.
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1400 - CASSI1415


CASSI1411E

The attempt to inform the region manager of the animate server's termination failed due to an error in DosExecPgm.
System action:
The region manager will not know that the animate server has terminated. If a terminal is attached to that server it will wait indefinitely in a X-SYSTEM state.
Resolution:
None
Destination:
Console and standard error
Module:
dfhecics
Parent topic: CASSI1400 - CASSI1415


CASSI1412S

The attempt to start a CICS API server under animator control failed due to an error in execlp.
System action:
The animate server cannot be started so the process will terminate.
Resolution:
None
Destination:
Console and standard error
Module:
dfhecics
Parent topic: CASSI1400 - CASSI1415


CASSI1413S

The attempt to start a CICS API server under animator control failed due to $COBDIR\cli.lbr not being found.
System action:
The animate server cannot be started so the process will terminate.
Resolution:
Make sure that the file 'cli.lbr' is on $COBDIR and retry.
Destination:
Console and standard error
Module:
dfhecics
Parent topic: CASSI1400 - CASSI1415


CASSI1414S

The attempt to start a CICS API server under animator control failed due to $COBDIR\cobcli.lbr not being found.
System action:
The animate server cannot be started so the process will terminate.
Resolution:
Make sure that the file 'cobcli.lbr' is on $COBDIR and retry.
Destination:
Console and standard error
Module:
dfhecics
Parent topic: CASSI1400 - CASSI1415


CASSI1415E

An error occurred loading dfheini1. Either the module dfheini1.gnt is not in $CASDIR/lib or the environment variable CASDIR is not properly set.
System action:
Client initialization is terminated.
Resolution:
Correct CASDIR or the location of dfheini1.gnt and retry.
Destination:
Standard out
Module:
dfheserv
Parent topic: CASSI1400 - CASSI1415


CASSI1416 - CASSI1600

  • CASSI1416S
    The attempt to start a CICS API server under GUI animator control failed due to $COBDIR\anim2.lbr not being found.
  • CASSI1417S
    The attempt to start a CICS API server under animator control in the single process region failed due to an illegal command line. The single process region will animate all tasks being run if '/a' is specified on the command line.
  • CASSI1418S
    The attempt to start a CICS API server under GUI animator control failed as the program was not running as a graphical application.
  • CASSI1419S
    The attempt to start a CICS API server under GUI animator control failed due to $COBDIR\mfcsi.lbr not being found.
  • CASSI1420S
    The name of the temporary storage/transient data file as specified in the SIT is illegal. The temporary storage/transient data file names are as follows:
  • CASSI1421S
    While attempting to initialize the temporary storage or transient data file an error occurred while connecting with the Fileshare server FS-server.
  • CASSI1422S
    While attempting to initialize the temporary storage or transient data file a run time error occurred.
  • CASSI1423S
    While attempting to initialize the temporary storage or transient data file a file access error occurred.
  • CASSI1424S
    While attempting to locate the temporary storage or transient data file an error occurred.
  • CASSI1425I
    The temporary storage recoverable/non-recoverable has been cold/warm started
  • CASSI1426I
    The transient data recoverable/non-recoverable has been cold/warm started
  • CASSI1427E
    The temporary storage recoverable/non-recoverable could not be cold/warm started
  • CASSI1428E
    The transient data recoverable/non-recoverable could not be cold/warm started
  • CASSI1500I
    A CAS CICS API server has started its initialization phase#
  • CASSI1501I
    The Event Manager Process has started its initialization phase#
  • CASSI1502S
    The Event Manager Process failed registration. The reason code is reason-code.
  • CASSI1503I
    The Event Manager Process has completed its initialization phase#
  • CASSI1600I
    A CAS CICS API server has successfully completed its initialization phase.
Parent topic: CASSI Error Messages


CASSI1416S

The attempt to start a CICS API server under GUI animator control failed due to $COBDIR\anim2.lbr not being found.
System action:
The animate server cannot be started so the process will terminate.
Resolution:
Make sure that the file 'anim2.lbr' is on $COBDIR and retry.
Destination:
Console and standard error
Module:
dfhecics
Parent topic: CASSI1416 - CASSI1600


CASSI1417S

The attempt to start a CICS API server under animator control in the single process region failed due to an illegal command line. The single process region will animate all tasks being run if '/a' is specified on the command line.
System action:
The animate server cannot be started so the process will terminate.
Resolution:
Retype the command specifying '/a' to indicate that animator support is required.
Destination:
Console and standard error
Module:
dfhecics
Parent topic: CASSI1416 - CASSI1600


CASSI1418S

The attempt to start a CICS API server under GUI animator control failed as the program was not running as a graphical application.
System action:
The animate server cannot be started so the process will terminate.
Resolution:
Either start the animate server using the graphical program trigger or remove the 'g' option from the command line.
Destination:
Console and standard error
Module:
dfhecics
Parent topic: CASSI1416 - CASSI1600


CASSI1419S

The attempt to start a CICS API server under GUI animator control failed due to $COBDIR\mfcsi.lbr not being found.
System action:
The animate server cannot be started so the process will terminate.
Resolution:
Make sure that the file 'mfcsi.lbr' is on $COBDIR and retry.
Destination:
Console and standard error
Module:
dfhecics
Parent topic: CASSI1416 - CASSI1600


CASSI1420S

The name of the temporary storage/transient data file as specified in the SIT is illegal. The temporary storage/transient data file names are as follows:
System action:
The system file can not be opened successfully so the region initialization will be unsuccessful.
Resolution:
Correct the name given in the SIT, making sure that no filename is given, only the path and that the directory exists.
Destination:
Console and standard error
Module:
dfhginit(dfhcptdi)
Parent topic: CASSI1416 - CASSI1600


CASSI1421S

While attempting to initialize the temporary storage or transient data file an error occurred while connecting with the Fileshare server FS-server.
System action:
The system file can not be opened successfully so the region initialization will be unsuccessful.
Resolution:
Make sure that the Fileshare server FS-server is running or correct the name given in the SIT.
Destination:
Console
Module:
dfhginit(dfhcptdi)
Parent topic: CASSI1416 - CASSI1600


CASSI1422S

While attempting to initialize the temporary storage or transient data file a run time error occurred.
System action:
The system file can not be opened successfully so the region initialization will be unsuccessful.
Resolution:
Destination:
Console
Module:
dfhginit(dfhcptdi)
Parent topic: CASSI1416 - CASSI1600


CASSI1423S

While attempting to initialize the temporary storage or transient data file a file access error occurred.
System action:
The system file can not be opened successfully so the region initialization will be unsuccessful.
Resolution:
Look up the file status codes and correct the error.
Destination:
Console and standard error
Module:
dfhginit(dfhcptdi)
Parent topic: CASSI1416 - CASSI1600


CASSI1424S

While attempting to locate the temporary storage or transient data file an error occurred.
System action:
The system file can not be opened successfully so the region initialization will be unsuccessful.
Resolution:
Look up the status code for the FS_LOCATE_FILE file call, correct the error specified and re-try.
Destination:
Console and standard error
Module:
dfhginit(dfhcptdi)
Parent topic: CASSI1416 - CASSI1600


CASSI1425I

The temporary storage recoverable/non-recoverable has been cold/warm started
System action:
None
Resolution:
None
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1416 - CASSI1600


CASSI1426I

The transient data recoverable/non-recoverable has been cold/warm started
System action:
None
Resolution:
None
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1416 - CASSI1600


CASSI1427E

The temporary storage recoverable/non-recoverable could not be cold/warm started
System action:
None
Resolution:
None
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1416 - CASSI1600


CASSI1428E

The transient data recoverable/non-recoverable could not be cold/warm started
System action:
None
Resolution:
None
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1416 - CASSI1600


CASSI1500I

A CAS CICS API server has started its initialization phase#
System action:
None
Resolution:
None
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1416 - CASSI1600


CASSI1501I

The Event Manager Process has started its initialization phase#
System action:
None
Resolution:
None
Destination:
Console and standard error
Module:
casevmgr
Parent topic: CASSI1416 - CASSI1600


CASSI1502S

The Event Manager Process failed registration. The reason code is reason-code.
System action:
The Eevent Manager Process is terminated.
Resolution:
Report failure to Micro Focus
Destination:
Console
Module:
casevmgr
Parent topic: CASSI1416 - CASSI1600


CASSI1503I

The Event Manager Process has completed its initialization phase#
System action:
None
Resolution:
None
Destination:
Console and standard error
Module:
casevmgr
Parent topic: CASSI1416 - CASSI1600


CASSI1600I

A CAS CICS API server has successfully completed its initialization phase.
System action:
Resolution:
None
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1416 - CASSI1600


CASSI1700 - CASSI1715

  • CASSI1700I
  • CASSI1701S
    A problem occurred allocating memory for the server communications buffer used for peer to peer data flows.
  • CASSI1702S
    An error occurred whilst initializing the server's PCA. The server will not complete its initialization.
  • CASSI1703S
    The registration of the server's TCA failed, the server will not complete its initialization.
  • CASSI1704S
    None
  • CASSI1705S
    None
  • CASSI1706I
    The server is registered as a debug server for terminal transaction
  • CASSI1707I
    The server is registered as a debug server for transaction
  • CASSI1708S
    The animation initialization was unsuccessful.
  • CASSI1709S
    An error occurred whilst starting a single user development region. A runtime lock could not be acquired indicating that another region is currently running.
  • CASSI1710S
    An error occurred whilst starting a single user development region. A run-time lock could not be acquired due to the error extended-file-status. The most likely reason is that the directory in which CICS Option creates the lock file,\system, is read-only.
  • CASSI1711S
    An error occurred whilst starting a region, a single user region was already running.
  • CASSI1712S
    An error occurred whilst starting a region. A runtime lock could not be acquired due to the error runtime-lock-status
  • CASSI1713S
    An error occurred on initial access to the resource definition file while initializing a single task region.
  • CASSI1714S
    An error occurred allocating memory for the dynamic subpool while initializing a single task region.
  • CASSI1715S
    The version of the resource definition file is not recognized.
Parent topic: CASSI Error Messages


CASSI1700I

System action:
Resolution:
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1700 - CASSI1715


CASSI1701S

A problem occurred allocating memory for the server communications buffer used for peer to peer data flows.
System action:
Function shipping, transaction routing, and APPC operations will cause the server to terminate abnormally. The system will continue to operate if these functions are avoided.
Resolution:
Research and resolve the problem associated with memory allocation indicated by the reason code.
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1700 - CASSI1715


CASSI1702S

An error occurred whilst initializing the server's PCA. The server will not complete its initialization.
System action:
Stop the server process.
Resolution:
Make sure that the region for which the server was to be started is running and retry.
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1700 - CASSI1715


CASSI1703S

The registration of the server's TCA failed, the server will not complete its initialization.
System action:
Stop the server process.
Resolution:
Make sure that the region is not currently in a shutdown state and retry.
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1700 - CASSI1715


CASSI1704S

None
System action:
None
Resolution:
None
Destination:
None
Module:
None
Parent topic: CASSI1700 - CASSI1715


CASSI1705S

None
System action:
None
Resolution:
None
Destination:
None
Module:
None
Parent topic: CASSI1700 - CASSI1715


CASSI1706I

The server is registered as a debug server for terminal transaction
System action:
All work for the above resource will be routed to this server
Resolution:
None
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1700 - CASSI1715


CASSI1707I

The server is registered as a debug server for transaction
System action:
All work for the above resource will be routed to this server
Resolution:
None
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1700 - CASSI1715


CASSI1708S

The animation initialization was unsuccessful.
System action:
Resolution:
None
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1700 - CASSI1715


CASSI1709S

An error occurred whilst starting a single user development region. A runtime lock could not be acquired indicating that another region is currently running.
System action:
The single user region will not initialize successfully.
Resolution:
None.
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1700 - CASSI1715


CASSI1710S

An error occurred whilst starting a single user development region. A run-time lock could not be acquired due to the error extended-file-status. The most likely reason is that the directory in which CICS Option creates the lock file,\system, is read-only.
System action:
The single user region will not initialize successfully.
Resolution:
Ensure that the directory \system is not read-only.
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1700 - CASSI1715


CASSI1711S

An error occurred whilst starting a region, a single user region was already running.
System action:
The region manager will not initialize successfully.
Resolution:
None.
Destination:
Console and standard error
Module:
dfhginit
Parent topic: CASSI1700 - CASSI1715


CASSI1712S

An error occurred whilst starting a region. A runtime lock could not be acquired due to the error runtime-lock-status
System action:
The region manager will not initialize successfully.
Resolution:
None.
Destination:
Console and standard error
Module:
dfhginit
Parent topic: CASSI1700 - CASSI1715


CASSI1713S

An error occurred on initial access to the resource definition file while initializing a single task region.
System action:
The region start is aborted.
Resolution:
Check the system setup for the region. Check that the resource definition file is physically accessible.
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1700 - CASSI1715


CASSI1714S

An error occurred allocating memory for the dynamic subpool while initializing a single task region.
System action:
The region start is aborted.
Resolution:
Check for a valid shared page specification in the specified sit.
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1700 - CASSI1715


CASSI1715S

The version of the resource definition file is not recognized.
System action:
The region start is aborted.
Resolution:
Check that the resource definition file is the intended file and that it is the proper version.
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1700 - CASSI1715


CASSI1716 - CASSI1730

  • CASSI1716S
    The version of the resource definition file is not recognized.
  • CASSI1717S
    The version of the resource definition file is not recognized.
  • CASSI1718I
    The 3270 emulation for DBCS and SI/SO is being loaded.
  • CASSI1719I
    The 3270 emulation for a single process system is being loaded.
  • CASSI1720S
    An attempt to start a region with a specified SIT SIT-name was unsuccessful as the SIT was not found in the resource definition file.
  • CASSI1721S
    The startup list specified in the SIT could not be located in the resource definition file. As no groups can be installed to the region the region will not be started.
  • CASSI1722S
    The startup list specified in the SIT did not contain any groups/resources in the resource definition file. As no groups can be installed to the region the region will not be started.
  • CASSI1723S
    The startup list specified in the SIT is invalid. As no groups can be installed to the region the region will not be started.
  • CASSI1724S
    The Program Load Table Pre-Initialization (PLTPI) list PLTPI-list-namewhich was specified in the SIT for the starting region could not be located in any of the groups installed to the system.
  • CASSI1725S
    The startup list specified in the SIT could not be located in the resource definition file. As no groups can be installed to the region the region will not be started.
  • CASSI1726S
    The startup list specified in the SIT did not contain any groups/resources in the resource definition file. As no groups can be installed to the region the region will not be started.
  • CASSI1727S
    The startup list specified in the SIT is invalid. As no groups can be installed to the region the region will not be started.
  • CASSI1728S
    The system tried to log on to DB manager selectedand failed to connect for the reason shown by the sqlcode detailed. This code should be detailed in the DB manager selected documentation. DB manager selected was specified in the SIT for connection at system startup time.
  • CASSI1729I
    The logon request was successful.
  • CASSI1730S
    The system failed to locate the LBR required for loading for DB manager selected.
Parent topic: CASSI Error Messages


CASSI1716S

The version of the resource definition file is not recognized.
System action:
The region start is aborted.
Resolution:
Check that the resource definition file is the intended file and that it is the proper version.
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1716 - CASSI1730


CASSI1717S

The version of the resource definition file is not recognized.
System action:
The region start is aborted.
Resolution:
Check that the resource definition file is the intended file and that it is the proper version.
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1716 - CASSI1730


CASSI1718I

The 3270 emulation for DBCS and SI/SO is being loaded.
System action:
Continue.
Resolution:
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1716 - CASSI1730


CASSI1719I

The 3270 emulation for a single process system is being loaded.
System action:
Continue.
Resolution:
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1716 - CASSI1730


CASSI1720S

An attempt to start a region with a specified SIT SIT-name was unsuccessful as the SIT was not found in the resource definition file.
System action:
The region will not be started.
Resolution:
Make sure that the SIT is defined in the region's resource definitions. If the record does not exist then either request that the system administrator create the required SIT or use another one.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1716 - CASSI1730


CASSI1721S

The startup list specified in the SIT could not be located in the resource definition file. As no groups can be installed to the region the region will not be started.
System action:
The region will not be started.
Resolution:
Make sure that the startup list specified in the SIT being used is correct and is defined in the resource definition file.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1716 - CASSI1730


CASSI1722S

The startup list specified in the SIT did not contain any groups/resources in the resource definition file. As no groups can be installed to the region the region will not be started.
System action:
The region will not be started.
Resolution:
Make sure that the startup list is defined correctly and that groups named contain resources which are defined.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1716 - CASSI1730


CASSI1723S

The startup list specified in the SIT is invalid. As no groups can be installed to the region the region will not be started.
System action:
The region will not be started.
Resolution:
Make sure that the startup list is defined correctly.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1716 - CASSI1730


CASSI1724S

The Program Load Table Pre-Initialization (PLTPI) list PLTPI-list-namewhich was specified in the SIT for the starting region could not be located in any of the groups installed to the system.
System action:
The region will not be started.
Resolution:
Make sure that the PLTPI list specified in the SIT is defined in a group which is installed to the system on system initialization. The list of groups to be installed to the system is defined in the startup list resource definition record.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1716 - CASSI1730


CASSI1725S

The startup list specified in the SIT could not be located in the resource definition file. As no groups can be installed to the region the region will not be started.
System action:
The region will not be started.
Resolution:
Make sure that the startup list specified in the SIT being used is correct and is defined in the resource definition file.
Destination:
Console and standard error.
Module:
dfhginit
Parent topic: CASSI1716 - CASSI1730


CASSI1726S

The startup list specified in the SIT did not contain any groups/resources in the resource definition file. As no groups can be installed to the region the region will not be started.
System action:
The region will not be started.
Resolution:
Make sure that the startup list is defined correctly and that groups named contain resources which are defined.
Destination:
Console and standard error.
Module:
dfhginit
Parent topic: CASSI1716 - CASSI1730


CASSI1727S

The startup list specified in the SIT is invalid. As no groups can be installed to the region the region will not be started.
System action:
The region will not be started.
Resolution:
Make sure that the startup list is defined correctly.
Destination:
Console and standard error.
Module:
dfhginit
Parent topic: CASSI1716 - CASSI1730


CASSI1728S

The system tried to log on to DB manager selectedand failed to connect for the reason shown by the sqlcode detailed. This code should be detailed in the DB manager selected documentation. DB manager selected was specified in the SIT for connection at system startup time.
System action:
The region will not be started.
Resolution:
Make sure that the DB manager selected is properly installed or turn off the selection flag in the SIT. Check that the DB name and password if required are specified correctly in the configuration file.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1716 - CASSI1730


CASSI1729I

The logon request was successful.
System action:
None
Resolution:
None
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1716 - CASSI1730


CASSI1730S

The system failed to locate the LBR required for loading for DB manager selected.
System action:
The region will not be started.
Resolution:
Make sure that the DB manager selected is properly installed and that all required environment variables for it have been set.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1716 - CASSI1730


CASSI1731 - CASSI1747

  • CASSI1731S
    The system failed to locate the LBR required for loading the MF IMS product
  • CASSI1732W
    The system received a return code other than 0 from initialization of the IMS product. The return code was not high enough to stop initialization. See $IMSWRK\IMSMTO.LOG for details.
  • CASSI1733S
    The system received a return code other than 0 from initialization of the IMS product. See $IMSWRK\IMSMTO.LOG for details.
  • CASSI1734I
    The system has successfully logged on to the Micro Focus IMS emulation product.
  • CASSI1735S
    The system failed to load the named support module at initialization.
  • CASSI1736S
    The RDO file SIT indicator is set to request connection to a particular database system automatically at start up time. Support for the database system is not available on this operating system.
  • CASSI1737W
    The system received a return code other than 0 from initialization of the MF/370 product. See MCO370.LOG for details.
  • CASSI1738I
    The MF/370 support is loaded at system initialization if present/required. This operation was successful.
  • CASSI1739W
    A non zero response was returned when trying to initialize the MVS control blocks.
  • CASSI1740W
    The system received a return code other than 0 from initialization of the IMS product. The return code was not high enough to stop initialization. See IMS log for details.
  • CASSI1741S
    The registration of the server's TCA failed, the debug server will not complete its initialization.
  • CASSI1742S
    The registration of the server's TCA failed as the requested 3270 terminal was not active in the region.
  • CASSI1743S
    The registration of the server's TCA failed as the requested non-facility transaction ID was not installed in the region.
  • CASSI1744I
    The PL/I support is loaded at system initialization if present/required. This operation was successful.
  • CASSI1745E
    The PL/I support is loaded at system initialization if present/required. This operation was unsuccessful.
  • CASSI1746W
    The system module required to support resident programs and user exits could not be loaded.
  • CASSI1747W Group specified in startup list not found
    The startup list contains a group that is not defined in the CICS resource definition file.
Parent topic: CASSI Error Messages


CASSI1731S

The system failed to locate the LBR required for loading the MF IMS product
System action:
The region will not be started.
Resolution:
Make sure that the IMSVS86 product is properly installed and that all required environment variables for it have been set.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1732W

The system received a return code other than 0 from initialization of the IMS product. The return code was not high enough to stop initialization. See $IMSWRK\IMSMTO.LOG for details.
System action:
The region will be started.
Resolution:
Make sure that the IMSVS86 product is properly installed and that all required environment variables for it have been set. Consult the IMS documentation for return code details.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1733S

The system received a return code other than 0 from initialization of the IMS product. See $IMSWRK\IMSMTO.LOG for details.
System action:
The region will not be started.
Resolution:
Make sure that the IMSVS86 product is properly installed and that all required environment variables for it have been set. Consult the IMS documentation for return code details.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1734I

The system has successfully logged on to the Micro Focus IMS emulation product.
System action:
Resolution:
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1735S

The system failed to load the named support module at initialization.
System action:
The region will not start successfully.
Resolution:
Check for the existence of the named module in $CASDIR/lib.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1736S

The RDO file SIT indicator is set to request connection to a particular database system automatically at start up time. Support for the database system is not available on this operating system.
System action:
The region will not start successfully.
Resolution:
Set the SIT flag indicator to 'N' and contact your sales rep/SE to ascertain the current status of support for the DB system.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1737W

The system received a return code other than 0 from initialization of the MF/370 product. See MCO370.LOG for details.
System action:
Region initialization will continue but MF/370 programs will not function correctly.
Resolution:
Make sure that the MF/370 product is properly installed and that all required environment variables for it have been set. Consult the MF/370 documentation for return code details.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1738I

The MF/370 support is loaded at system initialization if present/required. This operation was successful.
System action:
Region initialization will continue.
Resolution:
None.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1739W

A non zero response was returned when trying to initialize the MVS control blocks.
System action:
Region initialization will continue.
Resolution:
None.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1740W

The system received a return code other than 0 from initialization of the IMS product. The return code was not high enough to stop initialization. See IMS log for details.
System action:
The region will be started.
Resolution:
Consult the IMS documentation for return code details.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1741S

The registration of the server's TCA failed, the debug server will not complete its initialization.
System action:
Stop the server process.
Resolution:
Make sure that the region is not currently in a shutdown state and retry.
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1742S

The registration of the server's TCA failed as the requested 3270 terminal was not active in the region.
System action:
Stop the server process.
Resolution:
Make sure that the specified 3270 terminal ID is correct and the terminal in active and connected to this region.
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1743S

The registration of the server's TCA failed as the requested non-facility transaction ID was not installed in the region.
System action:
Stop the server process.
Resolution:
Make sure that the specified transaction ID is correct and that the group containing the transaction definition is included in the Startup List. A resource group can be dynamically installed using the CINS transaction.
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1744I

The PL/I support is loaded at system initialization if present/required. This operation was successful.
System action:
Region initialization will continue.
Resolution:
None.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1745E

The PL/I support is loaded at system initialization if present/required. This operation was unsuccessful.
System action:
Region initialization will continue but PL/I programs will not function correctly.
Resolution:
Make sure that the PL/I product is properly installed and that all required environment variables for it have been set.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1746W

The system module required to support resident programs and user exits could not be loaded.
System action:
Region initialization will continue but resident programs and user exits will not function correctly.
Resolution:
Make sure that dfh0load.dll is installed into the CICS system executables directory. Alternate versions are supplied in files\sys. Backup existing module and replace with alternate module and retry.
Destination:
Console and standard error.
Module:
dfheini1
Parent topic: CASSI1731 - CASSI1747


CASSI1747W Group specified in startup list not found

The startup list contains a group that is not defined in the CICS resource definition file.
System Action:
Region initialization will continue.
Resolution:
Check the resource definition and the startup list.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI1731 - CASSI1747


CASSI1800 - CASSI1900

  • CASSI1800S
    An error occurred whilst processing the global configuration file.
  • CASSI1801S
    An error occurred whilst processing the region configuration file.
  • CASSI1802I
    The server allows remote debuggers to attach
  • CASSI1803I
    A remote debug session has started. The animserv process is listening on the displayed port.
  • CASSI1804I
    An attempt to start a remote debug session has failed. The reason indicates the return code from the spawning of the animserv or cobremotedaemon process.
  • CASSI1805I
    A remote debug session has started. The animserv process is listening on the displayed port.
  • CASSI1806I
    A remote debug session has started. The animserv process is listening on the displayed port.
  • CASSI1807I
    The system was unable to load the support required to allow remote debugging.
  • CASSI1808I
    A remote debug session has started. The cobremotedaemon process is listening on the displayed port.
  • CASSI1809I Dynamic debugger attached. Cobdebugremote on port
    A remote debug session has started. The Cobdebugremote process is listening on the displayed port.
  • CASSI1810W Dynamic debugger port retrieval failed
    An attempt to start a dynamic debug session has failed. The ES Console Daemon could not retrieve the port number of the cobdebugremote process. A likely cause is that the cobdebugremote process failed to start correctly.
  • CASSI1839S
    An error occurred when processing the configuration file. Possible values of config-error-code are:
  • CASSI1840S
    An error occurred whilst processing the global configuration file.
  • CASSI1842S
    An error occurred whilst processing the configuration file.
  • CASSI1843S
    An unrecognized line was found in the configuration file at the line shown.
  • CASSI1844S
    The configuration file could not be found.
  • CASSI1845S
    An error occurred when creating the configuration save file.
  • CASSI1846S
    An error occurred when creating the configuration save file.
  • CASSI1847S
    An error occurred when reading the configuration save file.
  • CASSI1848S
    An error occurred when writing the configuration save file.
  • CASSI1849S
    An error occurred when writing the configuration save file, the directory specified in the CASLOCAL environment variable was invalid.
  • CASSI1851S
    An error occurred whilst processing the region configuration file.
  • CASSI1860S
    An error occurred whilst processing the global configuration file.
  • CASSI1861S
    An error occurred whilst processing the region configuration file.
  • CASSI1870S
    An error occurred whilst processing the global configuration file.
  • CASSI1871S
    An error occurred whilst processing the region configuration file.
  • CASSI1873S
    An error occurred whilst processing the region configuration file.
  • CASSI1872S
    An error occurred whilst processing the region configuration file.
  • CASSI1900S
    An IPS error occurred attaching to the server.
Parent topic: CASSI Error Messages


CASSI1800S

An error occurred whilst processing the global configuration file.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Correct the fault with the configuration file.
Destination:
Console
Module:
dfhtxs
Parent topic: CASSI1800 - CASSI1900


CASSI1801S

An error occurred whilst processing the region configuration file.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Correct the fault with the configuration file.
Destination:
Console
Module:
dfheini1
Parent topic: CASSI1800 - CASSI1900


CASSI1802I

The server allows remote debuggers to attach
System action:
None
Resolution:
None
Destination:
Console and standard error
Module:
dfhginit
Parent topic: CASSI1800 - CASSI1900


CASSI1803I

A remote debug session has started. The animserv process is listening on the displayed port.
System action:
None
Resolution:
None
Destination:
Console and standard error
Module:
casdbgfn
Parent topic: CASSI1800 - CASSI1900


CASSI1804I

An attempt to start a remote debug session has failed. The reason indicates the return code from the spawning of the animserv or cobremotedaemon process.
System action:
None
Resolution:
None
Destination:
Console and standard error
Module:
casdbgfn
Parent topic: CASSI1800 - CASSI1900


CASSI1805I

A remote debug session has started. The animserv process is listening on the displayed port.
System action:
None
Resolution:
None
Destination:
Console and standard error
Module:
casdbgfn
Parent topic: CASSI1800 - CASSI1900


CASSI1806I

A remote debug session has started. The animserv process is listening on the displayed port.
System action:
None
Resolution:
None
Destination:
Console and standard error
Module:
casdbgfn
Parent topic: CASSI1800 - CASSI1900


CASSI1807I

The system was unable to load the support required to allow remote debugging.
System action:
None
Resolution:
With task control tracing the entry f603 indicates the reason code (last 2 bytes)
Destination:
Console and standard error
Module:
casdbgfn
Parent topic: CASSI1800 - CASSI1900


CASSI1808I

A remote debug session has started. The cobremotedaemon process is listening on the displayed port.
System action:
None
Resolution:
None
Destination:
Console and standard error
Module:
casdbgfn
Parent topic: CASSI1800 - CASSI1900


CASSI1809I Dynamic debugger attached. Cobdebugremote on port

A remote debug session has started. The Cobdebugremote process is listening on the displayed port.
Module:
casdbgfn
Destination:
Console and standard error
Parent topic: CASSI1800 - CASSI1900


CASSI1810W Dynamic debugger port retrieval failed

An attempt to start a dynamic debug session has failed. The ES Console Daemon could not retrieve the port number of the cobdebugremote process. A likely cause is that the cobdebugremote process failed to start correctly.
Module:
casdbgfn
Destination:
Console and standard error
Parent topic: CASSI1800 - CASSI1900


CASSI1839S

An error occurred when processing the configuration file. Possible values of config-error-code are:
System action:
The CICS server will not initialize successfully.
Resolution:
Correct the configuration file / command line and retry.
Destination:
Console
Module:
dfheini1
Parent topic: CASSI1800 - CASSI1900


CASSI1840S

An error occurred whilst processing the global configuration file.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Correct the fault with the configuration file.
Destination:
Console
Module:
dfhmd
Parent topic: CASSI1800 - CASSI1900


CASSI1842S

An error occurred whilst processing the configuration file.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Correct the fault with the configuration file.
Destination:
Console
Module:
dfhmd
Parent topic: CASSI1800 - CASSI1900


CASSI1843S

An unrecognized line was found in the configuration file at the line shown.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Correct the fault with the configuration file ensuring that the line contains a valid configuration item.
Destination:
Console
Module:
dfhmd
Parent topic: CASSI1800 - CASSI1900


CASSI1844S

The configuration file could not be found.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Make sure that CASDIR is set correctly and that the configuration file exists.
Destination:
Console
Module:
dfhmd
Parent topic: CASSI1800 - CASSI1900


CASSI1845S

An error occurred when creating the configuration save file.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Destination:
Console
Module:
dfhmd
Parent topic: CASSI1800 - CASSI1900


CASSI1846S

An error occurred when creating the configuration save file.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Destination:
Console
Module:
dfhmd
Parent topic: CASSI1800 - CASSI1900


CASSI1847S

An error occurred when reading the configuration save file.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Destination:
Console
Module:
dfhmd
Parent topic: CASSI1800 - CASSI1900


CASSI1848S

An error occurred when writing the configuration save file.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Destination:
Console
Module:
dfhmd
Parent topic: CASSI1800 - CASSI1900


CASSI1849S

An error occurred when writing the configuration save file, the directory specified in the CASLOCAL environment variable was invalid.
System action:
The console daemon will not initialize successfully.
Resolution:
Check that the directory that is specified in CASLOCAL is valid and retry.
Destination:
Console
Module:
dfhmd
Parent topic: CASSI1800 - CASSI1900


CASSI1851S

An error occurred whilst processing the region configuration file.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Correct the fault with the configuration file.
Destination:
Console
Module:
dfhgtrtd
Parent topic: CASSI1800 - CASSI1900


CASSI1860S

An error occurred whilst processing the global configuration file.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Correct the fault with the configuration file.
Destination:
Console
Module:
dfhginit
Parent topic: CASSI1800 - CASSI1900


CASSI1861S

An error occurred whilst processing the region configuration file.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Correct the fault with the configuration file.
Destination:
Console
Module:
dfhginit
Parent topic: CASSI1800 - CASSI1900


CASSI1870S

An error occurred whilst processing the global configuration file.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Correct the fault with the configuration file.
Destination:
Console
Module:
dfhecics
Parent topic: CASSI1800 - CASSI1900


CASSI1871S

An error occurred whilst processing the region configuration file.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Correct the fault with the configuration file.
Destination:
Console
Module:
dfhecics
Parent topic: CASSI1800 - CASSI1900


CASSI1873S

An error occurred whilst processing the region configuration file.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Correct the fault with the configuration file.
Destination:
Console
Module:
dfhecics
Parent topic: CASSI1800 - CASSI1900


CASSI1872S

An error occurred whilst processing the region configuration file.
System action:
The console daemon or region manager will not initialize successfully.
Resolution:
Correct the fault with the configuration file.
Destination:
Console
Module:
dfhecics
Parent topic: CASSI1800 - CASSI1900


CASSI1900S

An IPS error occurred attaching to the server.
System action:
Terminate the requesting process
Resolution:
Check system IPC resources.
Destination:
Standard error
Module:
config-module(dfhcpcfp)
Parent topic: CASSI1800 - CASSI1900


CASSI2000 - CASSI2152

  • CASSI2000I
    The 3270 printer daemon has begun its initialization phase.
  • CASSI2001I
    The 3270 printer daemon has successfully completed its initialization phase.
  • CASSI2002S
    The 3270 printer daemon has failed to initialize its pca
  • CASSI2003S
    The 3270 printer daemon has failed to initialize as it could not read the region configuration file.
  • CASSI2004S
    The 3270 printer daemon has failed to initialize as its registration failed.
  • CASSI2005S
    The 3270 printer daemon has failed to initialize as it could not read the global configuration file.
  • CASSI2006I
    The 3270 printer daemon has successfully installed the user exit DFHUPRNT.
  • CASSI2100E
    An error occurred while attempting to initialize the 3270 terminal emulator
  • CASSI2101E
    An error occurred while processing the command line passed to the 3270 terminal emulator
  • CASSI2102E
    An error occurred while attempting to initialize the 3270 terminal emulator
  • CASSI2103E
    An error occurred while initializing the 3270 terminal emulator
  • CASSI2104E
    An error occurred while initializing the 3270 terminal emulator. Auto-install may have rejected the terminals connection to the region.
  • CASSI2105I
    The 3270 terminal has begun its initialization phase
  • CASSI2106E
    The COBOL run time system could not be located.
  • CASSI2107E
    The module dfht3270.gnt could not be located.
  • CASSI2108E
    An error occurred while attempting to connect the 3270 terminal emulator to the target region. The region is not yet initialized or has been terminated.
  • CASSI2109E
    An error occurred while attempting to connect the 3270 terminal emulator to the target region. The module dfh0cfg could not be found.
  • CASSI2110E
    An error occurred while attempting to connect the 3270 terminal emulator to the target region. The module dfh0msg could not be found.
  • CASSI2111E
    An error occurred while attempting to connect the 3270 terminal emulator to the target region. The thin client could not successfully process the configuration file.
  • CASSI2112E
    An error occurred while attempting to connect the 3270 terminal emulator to the target region. The global configuration could not be retrieved.
  • CASSI2113E
    An error occurred while attempting to connect the 3270 terminal emulator to the target region. The region configuration could not be retrieved.
  • CASSI2114E
    An error occurred while attempting to connect the 3270 terminal emulator to the target region. The error was unexpected, the return code was %1s
  • CASSI2115E
    An error occurred while attempting to connect the 3270 terminal emulator to the target region. The terminal setup was rejected by the target region
  • CASSI2116E
    An error occurred loading dfhtinit. Either the module dfhtinit.gnt is not in $CASDIR/lib or the environment variable CASDIR is not properly set.
  • CASSI2117I
    This message is put on the screen to give information to the user in case the connect process takes an unexpected amount of time. If this message persists without further activity the problem may be that there is not an available server on the target region to process the client installation. If this client is connecting to a remote region and that region is not currently available, the system may take up to two minutes to recognize the problem.
  • CASSI2150E
    An error occurred loading dfhtinit. Either the module dfhtinit.gnt is not in $CASDIR/lib or the environment variable CASDIR is not properly set.
  • CASSI2151W
    As part of terminal initialization the auto-install process modified the default terminal screen size. The terminal device attempted to dynamically change the physical screen size to support the new terminal model. The terminal failed to change the physical screen size, the return code was return-code. For example the terminal may have started in MOD2 but as part of auto-install a MOD4 screen was requested.
  • CASSI2152W
    As part of terminal initialization the auto-install process modified the default terminal screen size. The terminal device attempted to dynamically change the physical screen size to support the new terminal model. The terminal failed to change the physical screen size, the return code was return-code. For example the terminal may have started in MOD2 but as part of auto-install a MOD4 screen was requested.
Parent topic: CASSI Error Messages


CASSI2000I

The 3270 printer daemon has begun its initialization phase.
System action:
Initialize the printer daemon.
Resolution:
None
Destination:
Console and standard error
Module:
dfht3prt
Parent topic: CASSI2000 - CASSI2152


CASSI2001I

The 3270 printer daemon has successfully completed its initialization phase.
System action:
The printer daemon will now attempt to install all defined printers.
Resolution:
None
Destination:
Console and standard error
Module:
dfht3prt
Parent topic: CASSI2000 - CASSI2152


CASSI2002S

The 3270 printer daemon has failed to initialize its pca
System action:
The printer daemon will not initialize successfully.
Resolution:
None
Destination:
Console and standard error
Module:
dfht3prt
Parent topic: CASSI2000 - CASSI2152


CASSI2003S

The 3270 printer daemon has failed to initialize as it could not read the region configuration file.
System action:
The printer daemon will not initialize successfully.
Resolution:
None
Destination:
Console and standard error
Module:
dfht3prt
Parent topic: CASSI2000 - CASSI2152


CASSI2004S

The 3270 printer daemon has failed to initialize as its registration failed.
System action:
The printer daemon will not initialize successfully.
Resolution:
None
Destination:
Console and standard error
Module:
dfht3prt
Parent topic: CASSI2000 - CASSI2152


CASSI2005S

The 3270 printer daemon has failed to initialize as it could not read the global configuration file.
System action:
The printer daemon will not initialize successfully.
Resolution:
None
Destination:
Console and standard error
Module:
dfht3prt
Parent topic: CASSI2000 - CASSI2152


CASSI2006I

The 3270 printer daemon has successfully installed the user exit DFHUPRNT.
System action:
This exit will be used for all print requests.
Resolution:
None
Destination:
Console and standard error
Module:
dfht3prt
Parent topic: CASSI2000 - CASSI2152


CASSI2100E

An error occurred while attempting to initialize the 3270 terminal emulator
System action:
Return to operating system prompt
Resolution:
None
Destination:
Standard out
Module:
dfht3270
Parent topic: CASSI2000 - CASSI2152


CASSI2101E

An error occurred while processing the command line passed to the 3270 terminal emulator
System action:
Return to operating system prompt
Resolution:
Correct the command line parameters and retry the command
Destination:
Standard out
Module:
dfht3270
Parent topic: CASSI2000 - CASSI2152


CASSI2102E

An error occurred while attempting to initialize the 3270 terminal emulator
System action:
Return to operating system prompt
Resolution:
Ensure that the current screen size is one which is supported by the 3270 terminal emulator
Destination:
Standard out
Module:
dfht3270
Parent topic: CASSI2000 - CASSI2152


CASSI2103E

An error occurred while initializing the 3270 terminal emulator
System action:
Return to operating system prompt
Resolution:
Make sure that the region you wish to connect to is running and try again.
Destination:
Standard out
Module:
dfht3270
Parent topic: CASSI2000 - CASSI2152


CASSI2104E

An error occurred while initializing the 3270 terminal emulator. Auto-install may have rejected the terminals connection to the region.
System action:
Return to operating system prompt
Resolution:
None
Destination:
Standard out
Module:
dfht3270
Parent topic: CASSI2000 - CASSI2152


CASSI2105I

The 3270 terminal has begun its initialization phase
System action:
None
Resolution:
None
Destination:
Standard out
Module:
dfht3270
Parent topic: CASSI2000 - CASSI2152


CASSI2106E

The COBOL run time system could not be located.
System action:
The 3270 thin client will not be started.
Resolution:
Ensure that the COBDIR environment variable is set and retry.
Destination:
Standard out
Module:
dfht3270.c
Parent topic: CASSI2000 - CASSI2152


CASSI2107E

The module dfht3270.gnt could not be located.
System action:
The 3270 thin client will not be started.
Resolution:
Ensure that the directory containing dfht3270.gnt is on your COBPATH environment variable.
Destination:
Standard out
Module:
dfht3270.c
Parent topic: CASSI2000 - CASSI2152


CASSI2108E

An error occurred while attempting to connect the 3270 terminal emulator to the target region. The region is not yet initialized or has been terminated.
System action:
Return to operating system prompt
Resolution:
Retry the command when the region is active
Destination:
Standard out
Module:
dfht3270
Parent topic: CASSI2000 - CASSI2152


CASSI2109E

An error occurred while attempting to connect the 3270 terminal emulator to the target region. The module dfh0cfg could not be found.
System action:
Return to operating system prompt
Resolution:
Make sure that the missing module is in $CASDIR/lib
Destination:
Standard out
Module:
dfht3270
Parent topic: CASSI2000 - CASSI2152


CASSI2110E

An error occurred while attempting to connect the 3270 terminal emulator to the target region. The module dfh0msg could not be found.
System action:
Return to operating system prompt
Resolution:
Make sure that the missing module is in $CASDIR/lib
Destination:
Standard out
Module:
dfht3270
Parent topic: CASSI2000 - CASSI2152


CASSI2111E

An error occurred while attempting to connect the 3270 terminal emulator to the target region. The thin client could not successfully process the configuration file.
System action:
Return to operating system prompt
Resolution:
Ensure that the configuration file is valid.
Destination:
Standard out
Module:
dfht3270
Parent topic: CASSI2000 - CASSI2152


CASSI2112E

An error occurred while attempting to connect the 3270 terminal emulator to the target region. The global configuration could not be retrieved.
System action:
Return to operating system prompt
Resolution:
Destination:
Standard out
Module:
dfht3270
Parent topic: CASSI2000 - CASSI2152


CASSI2113E

An error occurred while attempting to connect the 3270 terminal emulator to the target region. The region configuration could not be retrieved.
System action:
Return to operating system prompt
Resolution:
None
Destination:
Standard out
Module:
dfht3270
Parent topic: CASSI2000 - CASSI2152


CASSI2114E

An error occurred while attempting to connect the 3270 terminal emulator to the target region. The error was unexpected, the return code was %1s
System action:
Return to operating system prompt
Resolution:
none
Destination:
Standard out
Module:
dfht3270
Parent topic: CASSI2000 - CASSI2152


CASSI2115E

An error occurred while attempting to connect the 3270 terminal emulator to the target region. The terminal setup was rejected by the target region
System action:
Return to operating system prompt
Resolution:
None
Destination:
Standard out
Module:
dfht3270
Parent topic: CASSI2000 - CASSI2152


CASSI2116E

An error occurred loading dfhtinit. Either the module dfhtinit.gnt is not in $CASDIR/lib or the environment variable CASDIR is not properly set.
System action:
Client initialization is terminated.
Resolution:
Correct CASDIR or the location of dfhtinit.gnt and retry.
Destination:
Standard out
Module:
dfht3270, dfht32db (dfhcpt3p)
Parent topic: CASSI2000 - CASSI2152


CASSI2117I

This message is put on the screen to give information to the user in case the connect process takes an unexpected amount of time. If this message persists without further activity the problem may be that there is not an available server on the target region to process the client installation. If this client is connecting to a remote region and that region is not currently available, the system may take up to two minutes to recognize the problem.
System action:
Client initialization continues.
Resolution:
None
Destination:
Standard out
Module:
dfht3270, dfht32db (dfhcpt3p)
Parent topic: CASSI2000 - CASSI2152


CASSI2150E

An error occurred loading dfhtinit. Either the module dfhtinit.gnt is not in $CASDIR/lib or the environment variable CASDIR is not properly set.
System action:
Client initialization is terminated.
Resolution:
Correct CASDIR or the location of dfhtinit.gnt and retry.
Destination:
Standard out
Module:
dfhtasci
Parent topic: CASSI2000 - CASSI2152


CASSI2151W

As part of terminal initialization the auto-install process modified the default terminal screen size. The terminal device attempted to dynamically change the physical screen size to support the new terminal model. The terminal failed to change the physical screen size, the return code was return-code. For example the terminal may have started in MOD2 but as part of auto-install a MOD4 screen was requested.
System action:
The new terminal model size is ignored and the terminal switches back to the original default sizes.
Resolution:
Make sure that the current display mode supports the requested screen size. For example MOD5 may only be supported in a window rather than a full screen, or the font size of the window is too large to support the screen size.
Destination:
Standard out
Module:
dfht32sb/dfht32db (dfhcpt3t)
Parent topic: CASSI2000 - CASSI2152


CASSI2152W

As part of terminal initialization the auto-install process modified the default terminal screen size. The terminal device attempted to dynamically change the physical screen size to support the new terminal model. The terminal failed to change the physical screen size, the return code was return-code. For example the terminal may have started in MOD2 but as part of auto-install a MOD4 screen was requested.
System action:
The new terminal model size is ignored and the terminal switches back to the original default sizes.
Resolution:
Make sure that the current display mode supports the requested screen size. For example MOD5 may only be supported in a window rather than a full screen, or the font size of the window is too large to support the screen size.
Destination:
Standard out
Module:
dfhe3270/dfhe32db (dfhcpt3t)
Parent topic: CASSI2000 - CASSI2152


CASSI2201 - CASSI4005

  • CASSI2201I
    The spool service has successfully completed its initialization phase.
  • CASSI2202E
    Error.
  • CASSI2203E
    A file I/O error has occurred while submitting JCL to the internal reader.
  • CASSI2204E
    A file I/O error has occurred while writing a report to the spooler.
  • CASSI2205E
    An error has occurred while interfacing with the MVS Jobstep Resource Manager.
  • CASSI2206E
    Error.
  • CASSI4000W
    The project database is accessed at region initialization to retrieve the CICS system properties. This information could not be accessed.
  • CASSI4001W
    The project database is accessed at region initialization to retrieve the CICS system properties. This project setting could not be accessed.
  • CASSI4002W
    An error occured whilst binding to the MF Directory Server.
  • CASSI4003W
    An error occured whilst retrieving the ES configuration from the MF Directory Server.
  • CASSI4004W
    An error occured whilst binding to the MF Directory Server.
  • CASSI4005I
    The system successfully bound to MFDS-address.
Parent topic: CASSI Error Messages


CASSI2201I

The spool service has successfully completed its initialization phase.
System action:
None.
Resolution:
None
Destination:
Console and standard error
Module:
dfhgspol
Parent topic: CASSI2201 - CASSI4005


CASSI2202E

Error.
System action:
None.
Resolution:
None
Destination:
Console and standard error
Module:
dfhgspol
Parent topic: CASSI2201 - CASSI4005


CASSI2203E

A file I/O error has occurred while submitting JCL to the internal reader.
System action:
Process terminates.
Resolution:
None
Destination:
Console and standard error
Module:
dfhespol
Parent topic: CASSI2201 - CASSI4005


CASSI2204E

A file I/O error has occurred while writing a report to the spooler.
System action:
Process terminates.
Resolution:
None
Destination:
Console and standard error
Module:
dfhespol
Parent topic: CASSI2201 - CASSI4005


CASSI2205E

An error has occurred while interfacing with the MVS Jobstep Resource Manager.
System action:
Process terminates.
Resolution:
None
Destination:
Console and standard error
Module:
dfhespol
Parent topic: CASSI2201 - CASSI4005


CASSI2206E

Error.
System action:
None.
Resolution:
Ensure that Enterprise Server is configured to use SSTM. Edit server's "Configuration Information":
Destination:
Console and standard error
Module:
dfhgspol
Parent topic: CASSI2201 - CASSI4005


CASSI4000W

The project database is accessed at region initialization to retrieve the CICS system properties. This information could not be accessed.
System action:
Continue initialization using SIT defaults.
Resolution:
None
Destination:
Console and standard error
Module:
dfhcpism
Parent topic: CASSI2201 - CASSI4005


CASSI4001W

The project database is accessed at region initialization to retrieve the CICS system properties. This project setting could not be accessed.
System action:
Continue initialization using SIT defaults.
Resolution:
None
Destination:
Console and standard error
Module:
dfhcpism
Parent topic: CASSI2201 - CASSI4005


CASSI4002W

An error occured whilst binding to the MF Directory Server.
System action:
Continue initialization using defaults.
Resolution:
None
Destination:
Console and standard error
Module:
dfhcpism
Parent topic: CASSI2201 - CASSI4005


CASSI4003W

An error occured whilst retrieving the ES configuration from the MF Directory Server.
System action:
Continue initialization using defaults.
Resolution:
None
Destination:
Console and standard error
Module:
dfhcpism
Parent topic: CASSI2201 - CASSI4005


CASSI4004W

An error occured whilst binding to the MF Directory Server.
System action:
Continue initialization using defaults.
Resolution:
None
Destination:
Console and standard error
Module:
dfhcpism
Parent topic: CASSI2201 - CASSI4005


CASSI4005I

The system successfully bound to MFDS-address.
System action:
Continue initialization.
Resolution:
None
Destination:
Console and standard error
Module:
dfhcpism
Parent topic: CASSI2201 - CASSI4005


CASSI5000 - CASSI5040

  • CASSI5000I
    Startup PLT processing has started using the plt-name list.
  • CASSI5001I
    Startup PLT processing was entered, but no list was specified.
  • CASSI5002S
    The Resource Definition file could not be opened to read the PLTPI program list table.
  • CASSI5003S
    The specified PLTPI program list table could not be found in the Resource Definition file.
  • CASSI5004S
    The specified PLTPI program list table was not present in the installed PPT.
  • CASSI5005S
    A transaction program abend occurred in the program program of the plt-name list during Phase 2 PLTPI processing.
  • CASSI5006S
    The named program specified could not be found and resulted in a PGMIDERR.
  • CASSI5007E
    The system shared memory resource limit has been reached. The region was in startup processing, and can not continue.
  • CASSI5010I
    All run-once (phase 1) and all run-on-evey-SEP (phase 2) PLT PI (Program List Table Post Initialization) programs have run on this SEP successfully. Critical post initialization processing has been completed using the plt-name list.
  • CASSI5012I Successfully negotiated with ES Cluster manager APPLID of ES Cluster manager
    The ES cluster member has successfully negotiated with the ES Cluster manager.
  • CASSI5013W Warning failed to negotiate with node APPLID of node., Reason for negotiation failure e.g. catalog path mismatch.
    All nodes must have the same catalog and data set paths as the ES Cluster manager. If either of these differ, the node region shuts down.
  • CASSI5014S Severe error in ES Cluster negotiation with Reason for negotiation failure e.g. catalog path mismatch. (), region terminating
    All nodes must have the same catalog and data set paths as the ES Cluster manager. If either of these differ, the node region shuts down.
  • CASSI5020I
    Startup Phase 2 PLT processing has started using the plt-name list.
  • CASSI5021I
    Startup Phase 2 PLT processing was entered, but no list was specified.
  • CASSI5022S
    The Resource Definition file could not be opened to read the PLTPI program list table.
  • CASSI5023S
    The specified PLTPI program list table could not be found in the Resource Definition file.
  • CASSI5024S
    The specified PLTPI program list table was not present in the installed PPT.
  • CASSI5025S
    A transaction program abend occurred in the program program of the plt-name list during Phase 2 PLTPI processing.
  • CASSI5026S
    The named program specified could not be found and resulted in a PGMIDERR.
  • CASSI5030I
    Startup Phase 2 PLT processing has completed successfully using the plt-name list.
  • CASSI5040I
    This reports the memory strategy and memory strategy retain count at the end of PLT-PI phase 1.
Parent topic: CASSI Error Messages


CASSI5000I

Startup PLT processing has started using the plt-name list.
System action:
PLT processing proceeds normally.
Resolution:
None
Destination:
Console
Module:
dfhzplt
Parent topic: CASSI5000 - CASSI5040


CASSI5001I

Startup PLT processing was entered, but no list was specified.
System action:
Startup proceeds normally.
Resolution:
None
Destination:
Console
Module:
dfhzplt
Parent topic: CASSI5000 - CASSI5040


CASSI5002S

The Resource Definition file could not be opened to read the PLTPI program list table.
System action:
PLT Processing is bypassed, startup continues.
Resolution:
None
Destination:
Console
Module:
dfhzplt
Parent topic: CASSI5000 - CASSI5040


CASSI5003S

The specified PLTPI program list table could not be found in the Resource Definition file.
System action:
PLT Processing is bypassed, startup continues.
Resolution:
None
Destination:
Console
Module:
dfhzplt
Parent topic: CASSI5000 - CASSI5040


CASSI5004S

The specified PLTPI program list table was not present in the installed PPT.
System action:
PLT Processing is bypassed, startup continues.
Resolution:
None
Destination:
Console
Module:
dfhzplt
Parent topic: CASSI5000 - CASSI5040


CASSI5005S

A transaction program abend occurred in the program program of the plt-name list during Phase 2 PLTPI processing.
System action:
PLT processing is terminated; startup is aborted.
Resolution:
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
Module:
dfhzplt
Parent topic: CASSI5000 - CASSI5040


CASSI5006S

The named program specified could not be found and resulted in a PGMIDERR.
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: CASSI5000 - CASSI5040


CASSI5007E

The system shared memory resource limit has been reached. The region was in startup processing, and can not continue.
System action:
Stop the region
Resolution:
If this is a common occurrence increase the number of shared pages in the SIT.
Destination:
System Console.
Module:
dfheserv
Parent topic: CASSI5000 - CASSI5040


CASSI5010I

All run-once (phase 1) and all run-on-evey-SEP (phase 2) PLT PI (Program List Table Post Initialization) programs have run on this SEP successfully. Critical post initialization processing has been completed using the plt-name list.
System action:
Startup proceeds normally.
Resolution:
None
Destination:
Console
Module:
dfhzplt
Parent topic: CASSI5000 - CASSI5040


CASSI5012I Successfully negotiated with ES Cluster manager APPLID of ES Cluster manager

The ES cluster member has successfully negotiated with the ES Cluster manager.
System Action:
Now able to participate as part of an ES cluster.
Resolution:
None.
Module:
caszccfa
Destination:
System Console.
Parent topic: CASSI5000 - CASSI5040


CASSI5013W Warning failed to negotiate with node APPLID of node., Reason for negotiation failure e.g. catalog path mismatch.

All nodes must have the same catalog and data set paths as the ES Cluster manager. If either of these differ, the node region shuts down.
System Action:
None.
Resolution:
Configure the node's JES catalog and data set paths to be the same as the ES Cluster manager's paths.
Module:
caszccfa
Destination:
System Console.
Parent topic: CASSI5000 - CASSI5040


CASSI5014S Severe error in ES Cluster negotiation with Reason for negotiation failure e.g. catalog path mismatch. (), region terminating

All nodes must have the same catalog and data set paths as the ES Cluster manager. If either of these differ, the node region shuts down.
System Action:
Stop the region.
Resolution:
Configure the node's JES catalog and data set paths to be the same as the ES Cluster manager's paths.
Module:
caszccfa
Destination:
System Console.
Parent topic: CASSI5000 - CASSI5040


CASSI5020I

Startup Phase 2 PLT processing has started using the plt-name list.
System action:
PLT processing proceeds normally.
Resolution:
None
Destination:
Console
Module:
dfhzplt
Parent topic: CASSI5000 - CASSI5040


CASSI5021I

Startup Phase 2 PLT processing was entered, but no list was specified.
System action:
Startup proceeds normally.
Resolution:
None
Destination:
Console
Module:
dfhzplt
Parent topic: CASSI5000 - CASSI5040


CASSI5022S

The Resource Definition file could not be opened to read the PLTPI program list table.
System action:
PLT Processing is bypassed, startup continues.
Resolution:
None
Destination:
Console
Module:
dfhzplt
Parent topic: CASSI5000 - CASSI5040


CASSI5023S

The specified PLTPI program list table could not be found in the Resource Definition file.
System action:
PLT Processing is bypassed, startup continues.
Resolution:
None
Destination:
Console
Module:
dfhzplt
Parent topic: CASSI5000 - CASSI5040


CASSI5024S

The specified PLTPI program list table was not present in the installed PPT.
System action:
PLT Processing is bypassed, startup continues.
Resolution:
None
Destination:
Console
Module:
dfhzplt
Parent topic: CASSI5000 - CASSI5040


CASSI5025S

A transaction program abend occurred in the program program of the plt-name list during Phase 2 PLTPI processing.
System action:
PLT processing is terminated; startup is aborted.
Resolution:
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
Module:
dfhzplt
Parent topic: CASSI5000 - CASSI5040


CASSI5026S

The named program specified could not be found and resulted in a PGMIDERR.
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: CASSI5000 - CASSI5040


CASSI5030I

Startup Phase 2 PLT processing has completed successfully using the plt-name list.
System action:
Startup proceeds normally.
Resolution:
None
Destination:
Console
Module:
dfhzplt
Parent topic: CASSI5000 - CASSI5040


CASSI5040I

This reports the memory strategy and memory strategy retain count at the end of PLT-PI phase 1.
System action:
Startup proceeds normally.
Resolution:
None
Destination:
Console
Module:
dfhzplt
Parent topic: CASSI5000 - CASSI5040


CASSI6000 - CASSI8005

  • CASSI6000E
    The WebSphere MQ trigger monitor program (CKTI) failed to initialize successfully. This may be due to a WebSphere MQ configuration program or other region startup failure.
  • CASSI6001I
    The WebSphere MQ trigger monitor program (CKTI) initialized successfully and is monitoring initiation-queue.
  • CASSI6002I
    The WebSphere MQ parameters specified in the current SIT will be used instead of the XAT entry.
  • CASSI6003E
    The WebSphere MQ trigger monitor program failed to connect to the ASEE environment.
  • CASSI6004E
    The WebSphere MQ trigger monitor task failed to connect to the queue-manager-name queue manager.
  • CASSI6005I
    The WebSphere MQ trigger monitor task is about to connect to the queue-manager-name queue manager in order to monitor the queue-name initiation queue.
  • CASSI6006I
    The WebSphere MQ trigger monitor program (CKTI) client configuration MQSERVER environment variable value is environment-value.
  • CASSI6007I
    The WebSphere MQ support module has loaded successfully, no attempt was made to connect to the specified queue manager.
  • CASSI7000I
    During region initialization a connection definition was found where the netname matched the local applid. The sysid of the connection definition will override the sysid specified in the SIT.
  • CASSI7001I
    During region initialization a connection definition was found where the netname matched the local applid. The port number of the connection definition will override the port number specified in the SIT.
  • CASSI8001I
    The Enterprise Server region has started and caswait returned
  • CASSI8002E
    During region initialization a termination was detected.
  • CASSI8003I
    The Enterprise Server region has terminated and caswait returned
  • CASSI8004S
    An error occurred accessing the region configuration data. Typically this occurs when the region is not currently active.
  • CASSI8005S
    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.
Parent topic: CASSI Error Messages


CASSI6000E

The WebSphere MQ trigger monitor program (CKTI) failed to initialize successfully. This may be due to a WebSphere MQ configuration program or other region startup failure.
System action:
Stop WebSphere MQ trigger monitor
Resolution:
Check the reason code and correct problem if possible then restart the region.
Destination:
Console
Module:
dfhtmqgw
Parent topic: CASSI6000 - CASSI8005


CASSI6001I

The WebSphere MQ trigger monitor program (CKTI) initialized successfully and is monitoring initiation-queue.
System action:
None
Resolution:
None
Destination:
Console
Module:
dfhtmqgw
Parent topic: CASSI6000 - CASSI8005


CASSI6002I

The WebSphere MQ parameters specified in the current SIT will be used instead of the XAT entry.
System action:
None
Resolution:
None
Destination:
Console
Module:
dfhginit
Parent topic: CASSI6000 - CASSI8005


CASSI6003E

The WebSphere MQ trigger monitor program failed to connect to the ASEE environment.
System action:
Stop MQseries trigger monitor
Resolution:
Check the reason code and correct problem if possible then restart the region.
Destination:
Console
Module:
dfhtmqgw
Parent topic: CASSI6000 - CASSI8005


CASSI6004E

The WebSphere MQ trigger monitor task failed to connect to the queue-manager-name queue manager.
System action:
Stop MQseries trigger monitor
Resolution:
Check the reason code and correct problem if possible then restart the region.
Destination:
Console
Module:
dfhtmqgw
Parent topic: CASSI6000 - CASSI8005


CASSI6005I

The WebSphere MQ trigger monitor task is about to connect to the queue-manager-name queue manager in order to monitor the queue-name initiation queue.
System action:
None
Resolution:
None
Destination:
Console
Module:
dfhtmqgw
Parent topic: CASSI6000 - CASSI8005


CASSI6006I

The WebSphere MQ trigger monitor program (CKTI) client configuration MQSERVER environment variable value is environment-value.
System action:
None
Resolution:
None
Destination:
Console
Module:
dfhtmqgw
Parent topic: CASSI6000 - CASSI8005


CASSI6007I

The WebSphere MQ support module has loaded successfully, no attempt was made to connect to the specified queue manager.
System action:
None
Resolution:
None
Destination:
Console
Module:
dfhexa
Parent topic: CASSI6000 - CASSI8005


CASSI7000I

During region initialization a connection definition was found where the netname matched the local applid. The sysid of the connection definition will override the sysid specified in the SIT.
System action:
None
Resolution:
None
Destination:
Console
Module:
dfhcprdt
Parent topic: CASSI6000 - CASSI8005


CASSI7001I

During region initialization a connection definition was found where the netname matched the local applid. The port number of the connection definition will override the port number specified in the SIT.
System action:
None
Resolution:
None
Destination:
Console
Module:
dfhcprdt
Parent topic: CASSI6000 - CASSI8005


CASSI8001I

The Enterprise Server region has started and caswait returned
System action:
None
Resolution:
None
Destination:
Console and standard error.
Module:
caswait
Parent topic: CASSI6000 - CASSI8005


CASSI8002E

During region initialization a termination was detected.
System action:
None
Resolution:
Check console.log for errors.
Destination:
Standard error.
Module:
caswait
Parent topic: CASSI6000 - CASSI8005


CASSI8003I

The Enterprise Server region has terminated and caswait returned
System action:
None
Resolution:
None
Destination:
Standard error.
Module:
caswait
Parent topic: CASSI6000 - CASSI8005


CASSI8004S

An error occurred accessing the region configuration data. Typically this occurs when the region is not currently active.
System action:
Terminate the requesting process
Resolution:
Make sure the region is active and retry.
Destination:
Standard error
Module:
caswait
Parent topic: CASSI6000 - CASSI8005


CASSI8005S

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.
System action:
Terminate the requesting process
Resolution:
Make sure that the console daemon is active and retry.
Destination:
Standard error
Module:
caswait
Parent topic: CASSI6000 - CASSI8005


CASSI9001 - CASSI9025

  • CASSI9001E
    parameter is invalid for this command line.
  • CASSI9002E
    cmd-parm conflicts with or duplicates preceding parameters on the command line.
  • CASSI9003E
    parameter is invalid for this command line.
  • CASSI9004S
    The attempt to start a CICS API server under debugger control failed due to an error in DosExecPgm.
  • CASSI9005E
    The attempt to inform the region manager of the debug server's termination failed due to an error in DosExecPgm.
  • CASSI9006S
    The attempt to start a CICS API server under debugger control failed due to an error in execlp.
  • CASSI9007S
    The attempt to start a CICS API server under debugger control in the single process region failed due to an illegal command line. The single process region will debug all tasks being run if '/a' is specified on the command line.
  • CASSI9008I
    The server is registered as a debug server for terminal transaction
  • CASSI9009I
    The server is registered as a debug server for transaction
  • CASSI9010S
    The debug initialization was unsuccessful.
  • CASSI9011S
    The server working mode does not match the current environment. Either you are starting a 64bit server from a 32bit environment or a 32bit server from a 64bit environment.
  • CASSI9012E
    JCL support is not enabled because call to casspool failed with the inserted return code.
  • CASSI9013S GLM lock file exists and in use by Applid of the region that has the lock on casglm.lck, ES Cluster Manager cannot start.
    The lock file is in use. ES Cluster member started before manager. Or shared resource used by a region not part of the ES Cluster.
  • CASSI9014S JCL support disabled. GLM lock file creation failed RC = return-code
    The lock file could not be created.
  • CASSI9015S JCL support disabled: RC return-code creating catalog folder path
    The Default Allocated Dataset folder could not be created.
  • CASSI9016S CASGLM.LCK Dataset in use by region Region name using the allocation area. JCL support disabled
    The lock file CASGLM.LCK is in use.
  • CASSI9017S Connection to ES Cluster manager remote-region (sysid sys-id) is disabled, verify and release global locks on ES cluster manager
    The CAS gateway connection to remote-region is lost after GLM timeout exceeded.
  • CASSI9018S Attempt to connect to a disabled ES Cluster manager remote-region (sysid sys-id)
    The CAS gateway connection to remote-region has been disabled.
  • CASSI9019S no connection available to the ES Cluster manager (sysid sys-id)
    The CAS gateway connection to sys-id cannot be found.
  • CASSI9020I Default RNLDEF created in Name of the file containing the RNL definitions (All SYSDSNs are Global resources).
    The file ESCLRNLs.cfg does not exits.
  • CASSI9021S RC Name of the file containing the RNL definitions attempting to create default RNLs file
    The default file ESCLRNLs.cfg could not be created.
  • CASSI9022E RC Name of the file containing the RNL definitions accessing RNLs file .
    The default file ESCLRNLs.cfg could not be written to.
  • CASSI9023E missing or invalid parameter parameter name in RNL record number record number.
    Invalid or missing parameter found in an RNLDEF.
  • CASSI9024I Number of records loaded RNLDEF loaded from ESCLRNLs.cfgNumber of records in error
    The ESCLRNLs.cfg file has been loaded.
  • CASSI9025I RNLDEFs received and installed from ES Cluster Manager Number of records loaded.
    All RNLs have been received and loaded from the GLM.
Parent topic: CASSI Error Messages


CASSI9001E

parameter is invalid for this command line.
System action:
Command processing terminates
Resolution:
None
Destination:
Console
Module:
dfhcpcmd
Parent topic: CASSI9001 - CASSI9025


CASSI9002E

cmd-parm conflicts with or duplicates preceding parameters on the command line.
System action:
Command processing terminates
Resolution:
None
Destination:
Console
Module:
dfhcpcmd
Parent topic: CASSI9001 - CASSI9025


CASSI9003E

parameter is invalid for this command line.
System action:
Command processing terminates
Resolution:
None
Destination:
Console
Module:
dfhcpcm2
Parent topic: CASSI9001 - CASSI9025


CASSI9004S

The attempt to start a CICS API server under debugger control failed due to an error in DosExecPgm.
System action:
The debug server cannot be started so the process will terminate.
Resolution:
None.
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI9001 - CASSI9025


CASSI9005E

The attempt to inform the region manager of the debug server's termination failed due to an error in DosExecPgm.
System action:
The region manager will not know that the debug server has terminated. If a terminal is attached to that server it will wait indefinitely in an X-SYSTEM state.
Resolution:
None
Destination:
Console and standard error
Module:
dfhecics
Parent topic: CASSI9001 - CASSI9025


CASSI9006S

The attempt to start a CICS API server under debugger control failed due to an error in execlp.
System action:
The debug server cannot be started so the process will terminate.
Resolution:
None
Destination:
Console and standard error
Module:
dfhecics
Parent topic: CASSI9001 - CASSI9025


CASSI9007S

The attempt to start a CICS API server under debugger control in the single process region failed due to an illegal command line. The single process region will debug all tasks being run if '/a' is specified on the command line.
System action:
The debug server cannot be started so the process will terminate.
Resolution:
Retype the command specifying '/a' to indicate that debugger support is required.
Destination:
Console and standard error
Module:
dfhecics
Parent topic: CASSI9001 - CASSI9025


CASSI9008I

The server is registered as a debug server for terminal transaction
System action:
All work for the above resource will be routed to this server
Resolution:
None
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI9001 - CASSI9025


CASSI9009I

The server is registered as a debug server for transaction
System action:
All work for the above resource will be routed to this server
Resolution:
None
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI9001 - CASSI9025


CASSI9010S

The debug initialization was unsuccessful.
System action:
Resolution:
None
Destination:
Console and standard error
Module:
dfheini1
Parent topic: CASSI9001 - CASSI9025


CASSI9011S

The server working mode does not match the current environment. Either you are starting a 64bit server from a 32bit environment or a 32bit server from a 64bit environment.
System action:
Resolution:
Check that both the server definition and the environment are the same.
Destination:
Console and standard error
Module:
dfhginit
Parent topic: CASSI9001 - CASSI9025


CASSI9012E

JCL support is not enabled because call to casspool failed with the inserted return code.
System action:
none
Resolution:
Perform an install repair on your system.
Destination:
ES Console
Module:
casmgr
Parent topic: CASSI9001 - CASSI9025


CASSI9013S GLM lock file exists and in use by Applid of the region that has the lock on casglm.lck, ES Cluster Manager cannot start.

The lock file is in use. ES Cluster member started before manager. Or shared resource used by a region not part of the ES Cluster.
System Action:
Stop initialization.
Resolution:
Stop region that is using the same catalog folder as region and restart.
Module:
casmgr
Destination:
Console and standard error
Parent topic: CASSI9001 - CASSI9025


CASSI9014S JCL support disabled. GLM lock file creation failed RC = return-code

The lock file could not be created.
System Action:
Disable JCL.
Resolution:
check RTS error code.
Module:
casmgr
Destination:
Console and standard error
Parent topic: CASSI9001 - CASSI9025


CASSI9015S JCL support disabled: RC return-code creating catalog folder path

The Default Allocated Dataset folder could not be created.
System Action:
Disable JCL.
Resolution:
Check RTS error code and JES configuration.
Module:
casmgr
Destination:
Console and standard error
Parent topic: CASSI9001 - CASSI9025


CASSI9016S CASGLM.LCK Dataset in use by region Region name using the allocation area. JCL support disabled

The lock file CASGLM.LCK is in use.
System Action:
Disable JCL.
Resolution:
Check region configuration.
Module:
casmgr
Destination:
Console and standard error
Parent topic: CASSI9001 - CASSI9025


CASSI9017S Connection to ES Cluster manager remote-region (sysid sys-id) is disabled, verify and release global locks on ES cluster manager

The CAS gateway connection to remote-region is lost after GLM timeout exceeded.
System Action:
Identify why connection was lost, release ES Cluster clients locks on ES Cluster manager if client ES cluster connection loss only.
Resolution:
No user action is required.
Module:
cassi
Destination:
Console
Parent topic: CASSI9001 - CASSI9025


CASSI9018S Attempt to connect to a disabled ES Cluster manager remote-region (sysid sys-id)

The CAS gateway connection to remote-region has been disabled.
System Action:
Verify why the connection to the ES cluster manager has been disabled.
Resolution:
No user action is required.
Module:
cassi
Destination:
Console
Parent topic: CASSI9001 - CASSI9025


CASSI9019S no connection available to the ES Cluster manager (sysid sys-id)

The CAS gateway connection to sys-id cannot be found.
System Action:
No sys action is required.
Resolution:
No user action is required.
Module:
cassi
Destination:
Console
Parent topic: CASSI9001 - CASSI9025


CASSI9020I Default RNLDEF created in Name of the file containing the RNL definitions (All SYSDSNs are Global resources).

The file ESCLRNLs.cfg does not exits.
System Action:
If specific RNLs are required, create the file in the folder containing the CATALOGUE.
Resolution:
Check region configuration.
Module:
casmgr
Destination:
Console
Parent topic: CASSI9001 - CASSI9025


CASSI9021S RC Name of the file containing the RNL definitions attempting to create default RNLs file

The default file ESCLRNLs.cfg could not be created.
System Action:
Identify why the file could not be created.
Resolution:
Check region configuration.
Module:
casmgr
Destination:
Console
Parent topic: CASSI9001 - CASSI9025


CASSI9022E RC Name of the file containing the RNL definitions accessing RNLs file .

The default file ESCLRNLs.cfg could not be written to.
System Action:
Identify why the file could not be accessed.
Resolution:
Check region configuration.
Module:
casmgr
Destination:
Console
Parent topic: CASSI9001 - CASSI9025


CASSI9023E missing or invalid parameter parameter name in RNL record number record number.

Invalid or missing parameter found in an RNLDEF.
System Action:
Correct the RNLs file.
Resolution:
none.
Module:
casmgr
Destination:
Console
Parent topic: CASSI9001 - CASSI9025


CASSI9024I Number of records loaded RNLDEF loaded from ESCLRNLs.cfgNumber of records in error

The ESCLRNLs.cfg file has been loaded.
System Action:
Correct the RNLs file if errors are flagged.
Resolution:
none.
Module:
casmgr
Destination:
Console
Parent topic: CASSI9001 - CASSI9025


CASSI9025I RNLDEFs received and installed from ES Cluster Manager Number of records loaded.

All RNLs have been received and loaded from the GLM.
Resolution:
none.
Module:
caszccfa
Destination:
Console
Parent topic: CASSI9001 - CASSI9025


CASSP Error Messages

  • CASSP0001 - CASSP0014
Parent topic: Enterprise Server Error Messages


CASSP0001 - CASSP0014

  • 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.
  • CASSP0012S
    IMS has abended during the current transaction running.
  • 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.
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
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.
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.
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.
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.
System action:
The transaction will abend.
Resolution:
Investigate why the syncpoint failed.
Destination:
Console and standard error.
Module:
dfhesync
Parent topic: CASSP0001 - CASSP0014


CASSP0012S

IMS has abended during the current transaction running.
System action:
The transaction and IMS will abend.
Resolution:
Investigate why IMS abended.
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.
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.
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

  • CASST0000 - CASST0020
  • CASST4000 - CASST4111
  • CASST5000 - CASST6002
Parent topic: Enterprise Server Error Messages


CASST0000 - CASST0020

  • 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
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
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.
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
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.
  • 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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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
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
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
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.
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.
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.
System action:
None.
Resolution:
None.
Destination:
Console and stdout
Module:
casstop
Parent topic: CASST0000 - CASST0020


CASST4000 - CASST4111

  • 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.
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.
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.
System action:
None
Resolution:
None
Destination:
Console (and Terminal)
Module:
dfhzcqit
Parent topic: CASST4000 - CASST4111


CASST4010I

Shutdown processing has begun using the indicated PLT.
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.
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.
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.
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.
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.
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.
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.
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.
System action:
None
Resolution:
None
Destination:
Console (and Terminal)
Module:
dfhzcqit
Parent topic: CASST4000 - CASST4111


CASST4110I

Shutdown processing has begun using the indicated PLT.
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.
System action:
Shutdown proceeding normally without PLT processing.
Resolution:
None
Destination:
Console
Module:
casrdo11
Parent topic: CASST4000 - CASST4111


CASST5000 - CASST6002

  • 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 WebSphere MQ 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
System action:
Shutdown proceeds normally.
Resolution:
None
Destination:
Console (and Terminal)
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5201I

The spool service has terminated normally
System Action:
None
Resolution:
None
Destination:
console
Module:
dfhgspol
Parent topic: CASST5000 - CASST6002


CASST5230I

The Event Process is terminating.
System Action:
None
Resolution:
None
Destination:
console
Module:
casevmgr
Parent topic: CASST5000 - CASST6002


CASST5231I

The Event Manager Process has terminated.
System Action:
None
Resolution:
None
Destination:
console
Module:
casevmgr
Parent topic: CASST5000 - CASST6002


CASST6002I

The WebSphere MQ trigger monitor program (CKTI) has disconnected from the queue manager and is terminating
System Action:
None
Resolution:
None
Destination:
console
Module:
dfhtmqgw
Parent topic: CASST5000 - CASST6002


CASTM Error Messages

  • CASTM5001 - CASTM5019
  • CASTM5020 - CASTM5039
  • CASTM5040 - CASTM5052
Parent topic: Enterprise Server Error Messages


CASTM5001 - CASTM5019

  • CASTM5001I IMS TM Control Process initialization started
    The server IMS TM Control Process initialization has started.
  • CASTM5002S IMS TM Control Process is not running in multi-threaded mode
    The IMS TM Control Process has not started with the required underlying thread support.
  • CASTM5003I IMS TM Control Process initialization complete
    The IMS TM Control Process has completed initialization.
  • CASTM5004S IMS TM Control Process registration failed, reason = reason-code
    The IMS TM Control Process failed registration. The reason code is reason-code.
  • CASTM5005S IMS TM Control Process storage allocation error
    The IMS TM Control Process experienced a problem allocating control blocks in local storage.
  • CASTM5006I ims-control-message
    The IMS TM Control Process issued a message. The text is ims-control-message.
  • CASTM5007I IMS TM Control Process termination started
    The IMS TM Control Process is terminating.
  • CASTM5008I IMS TM Control Process termination complete
    The IMS TM Control Process has terminated.
  • CASTM5009I IMS TM Control is operating with EBCDIC bias
    The IMS Transactions that are defined to use system bias will execute in EBCDIC mode.
  • CASTM5010I IMS TM Control is operating with ASCII bias
    The IMS Transactions that are defined to use system bias will execute in ASCII mode.
  • CASTM5011I IMS TM Control Process restart in progress
    The IMS TM Control process has been restarted and recovery operations are in progress.
  • CASTM5012S IMS TM Control message queues init failed. Reason (reason-code)
    The IMS TM Control Process failed to initialize its message queues.
  • CASTM5013I IMS TM Control message queues cold started
    The IMS TM Message Queues have been cold started. No old message data has been retained.
  • CASTM5014W IMS TM messages queues not properly closed previously
    The IMS TM Message Queues were not properly colsed the last time they were accessed.
  • CASTM5015I IMS TM Queue File: queue-file-name
    queue-file-name is the name of the IMS Message Queues file that will be used during this execution of ES.
  • CASTM5016I IMS TM Queue File size: queue-block-count blocks (queue-file-size bytes)
    The allocated block count for the message queues is queue-block-count. These blocks are composed of a block header plus 254 segments, each consisting of 244 bytes of queue data. The total file size is queue-file-size bytes.
  • CASTM5017I IMS TM running withqueue-buffer-count Queue File buffers of buffer-size bytes each
    queue-buffer-count buffers are allocated for the message queues use during this execution of ES. Each buffer is buffer-size bytes in length.
  • CASTM5018W IMS TM Transaction transaction (ID: 'transaction-id') inflight (wait)
    Transaction transaction (ID: 'transaction-id') is waiting for a commit or roll-back.
  • CASTM5019E IMS ACB error-ACB error; transaction transaction stopped, reason: reason
    Transaction transaction has been stopped because of a problem encountered accessing its associated ACB error-ACB. Possible values for the reason code are: 1 - ACB not found. The psbname.ACB file was not found. 2 - Unable to open ACB file on disk. This is likely to be because of invalid permissions. 3 - Unable to allocate storage for ACB. Please contact Micro Focus SupportLine if you see this reason code. 4 - Unable to read ACB file from disk. This is likely to be because of invalid permissions. 5 - ACB file size incorrect. The physical file size does not match that stored in the ACB, indicating a corruption of the file. 6 - ACB name error. The name of the ACB file does not match name of the file it was generated from. 7 - Invalid ACB type, possible corruption. Please contact Micro Focus SupportLine if you see this reason code. 8 - ACB content failed CRC checking. This is most likely to be due to file corruption.
Parent topic: CASTM Error Messages


CASTM5001I IMS TM Control Process initialization started

The server IMS TM Control Process initialization has started.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5002S IMS TM Control Process is not running in multi-threaded mode

The IMS TM Control Process has not started with the required underlying thread support.
System Action:
The IMS TM Control Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5003I IMS TM Control Process initialization complete

The IMS TM Control Process has completed initialization.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5004S IMS TM Control Process registration failed, reason = reason-code

The IMS TM Control Process failed registration. The reason code is reason-code.
System Action:
The IMS TM Control Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5005S IMS TM Control Process storage allocation error

The IMS TM Control Process experienced a problem allocating control blocks in local storage.
System Action:
The IMS TM Control Process is terminated.
Resolution:
Notify Micro Focus Support.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5006I ims-control-message

The IMS TM Control Process issued a message. The text is ims-control-message.
System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5007I IMS TM Control Process termination started

The IMS TM Control Process is terminating.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5008I IMS TM Control Process termination complete

The IMS TM Control Process has terminated.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5009I IMS TM Control is operating with EBCDIC bias

The IMS Transactions that are defined to use system bias will execute in EBCDIC mode.
System Action:
None None.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5010I IMS TM Control is operating with ASCII bias

The IMS Transactions that are defined to use system bias will execute in ASCII mode.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5011I IMS TM Control Process restart in progress

The IMS TM Control process has been restarted and recovery operations are in progress.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5012S IMS TM Control message queues init failed. Reason (reason-code)

The IMS TM Control Process failed to initialize its message queues.

The reason code reason-code is one of the following:

0
Queue file anchor array size mismatch
1
Failure reading queue file header
2
Failure during create of the queue file
3
Failure writing the queue file headers
4
Failure allocating queue file buffers
5
Failure allocating storage for the free space array
6
Failure writing the free space array
7
Failure reading the free space array
8
Queue file header record size mismatch
9
Queue file record size mismatchror
A
Queue file record block number mismatchror

These codes may be followed by a ":" and RTS file IO error code.

System Action:
The IMS TM Control Process is terminated and IMS message processing is disabled.
Resolution:
Correct the message queues configuration and restart the Enterprise Server.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5013I IMS TM Control message queues cold started

The IMS TM Message Queues have been cold started. No old message data has been retained.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5014W IMS TM messages queues not properly closed previously

The IMS TM Message Queues were not properly colsed the last time they were accessed.
System Action:
ES will attempt to insure data integrity. Additional messages will report any problems with this process.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5015I IMS TM Queue File: queue-file-name

queue-file-name is the name of the IMS Message Queues file that will be used during this execution of ES.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5016I IMS TM Queue File size: queue-block-count blocks (queue-file-size bytes)

The allocated block count for the message queues is queue-block-count. These blocks are composed of a block header plus 254 segments, each consisting of 244 bytes of queue data. The total file size is queue-file-size bytes.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5017I IMS TM running withqueue-buffer-count Queue File buffers of buffer-size bytes each

queue-buffer-count buffers are allocated for the message queues use during this execution of ES. Each buffer is buffer-size bytes in length.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5018W IMS TM Transaction transaction (ID: 'transaction-id') inflight (wait)

Transaction transaction (ID: 'transaction-id') is waiting for a commit or roll-back.
System Action:
Wait.
Resolution:
Choose disposition for transaction.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5019E IMS ACB error-ACB error; transaction transaction stopped, reason: reason

Transaction transaction has been stopped because of a problem encountered accessing its associated ACB error-ACB. Possible values for the reason code are: 1 - ACB not found. The psbname.ACB file was not found. 2 - Unable to open ACB file on disk. This is likely to be because of invalid permissions. 3 - Unable to allocate storage for ACB. Please contact Micro Focus SupportLine if you see this reason code. 4 - Unable to read ACB file from disk. This is likely to be because of invalid permissions. 5 - ACB file size incorrect. The physical file size does not match that stored in the ACB, indicating a corruption of the file. 6 - ACB name error. The name of the ACB file does not match name of the file it was generated from. 7 - Invalid ACB type, possible corruption. Please contact Micro Focus SupportLine if you see this reason code. 8 - ACB content failed CRC checking. This is most likely to be due to file corruption.
System Action:
Transaction aborted.
Resolution:
Correct ACB and retry.
Module:
castmc
Destination:
Console
Parent topic: CASTM5001 - CASTM5019


CASTM5020 - CASTM5039

  • CASTM5020S IMS TM Message Q version mismatch. Disk version is version
    The message queue disk file is written in a format that is not suppored by this version of IMS TM. The version on disk appears to be version.
  • CASTM5021S IMS TM Message Q upgrade or cold start is required. Version: version
    The message queue disk file is written in a format that is not suppored by this version of IMS TM. The current TM software version is version.
  • CASTM5022E Signon ID error: user ID user-identifier, group security-group at LU logical-unit
    A user tried to signon using TM with ID user-identifier, specifying secruity group security-group from logical unit logical-unit. The signon was rejected as an ID error.
  • CASTM5023E Signon password error: user ID user-identifier, group security-group at LU logical-unit
    A user tried to signon using TM with ID user-identifier, specifying secruity group security-group from logical unit logical-unit. The signon was rejected as a password error.
  • CASTM5024S Signon SAF error: user ID user-identifier, group security-group at LU logical-unit
    A user tried to signon using TM with ID user-identifier, specifying secruity group security-group from logical unit logical-unit. The signon was rejected because of a SAF error. An unexpected external security system error was returned on the verify call.
  • CASTM5025E Signon ID revoked: user ID user-identifier, group security-group at LU logical-unit
    A user tried to signon using TM with ID user-identifier, specifying secruity group security-group from logical unit logical-unit. The signon was rejected because the ID has been revoked.
  • CASTM5026E Signon password expired: user ID user-identifier, group security-group at LU logical-unit
    A user tried to signon using TM with ID user-identifier, specifying secruity group security-group from logical unit logical-unit. The signon was rejected because the password has expired.
  • CASTM5027I IMS TM MFS is operating with character attribute bias
    Unless otherwise specified in the TRANSACT macro, Message Format Services will operate on ASCII application supplied attributes as character attributes.
  • CASTM5028I IMS TM MFS is operating with binary attribute bias
    Unless otherwise specified in the TRANSACT macro, Message Format Services will operate on ASCII application supplied attributes as binary attributes.
  • CASTM5029I IMS TM MFS ASCII null character system bias is null-character
    Unless otherwise specified in the TRANSACT macro, Message Format Services will operate on ASCII application supplied messages using null-character as the MFS null character.
  • CASTM5030I IMS TM resource definitions and statistics cold started
    Resource definitions and statistics from the previous run's keypoint have been discarded.
  • CASTM5031I IMS TM resource definitions restored, statistics cold started
    Resource statistics from previous run's keypoint have been discarded. The resource definitions have been restored to the state recorded in the last keypoint.
  • CASTM5032I IMS TM resource definitions and statistics restored
    The resource definitions and statistics have been restored to the state recorded in the last keypoint.
  • CASTM5033S IMS TM message queue corruption detected: block queue-file-block
    The IMS TM message queue disk storage is corrupted.
  • CASTM5034S IMS TM message queue segment error: block queue-file-block; segment segment-number
    The IMS TM message queue disk storage is corrupted.
  • CASTM5035E IMS MPP ABEND; Transaction transaction stopped
    Transaction transaction has been stopped because of the message processing program experienced an ABEND.
  • CASTM5036S IMS TM Message Queue structure problem encountered
    The message queue disk file format is not recognized that is not suppored by this version of IMS TM. The version on disk appears to be .
  • CASTM5037I IMS TM old Queue File: queue-file-name
    queue-file-name is the name of the old IMS Message Queues file that was replaced as a part of cold starting the message queues.
  • CASTM5038I IMS transaction transaction marked as implicit wait for input
    transaction does further GU operations to the message queue after it has recieved a QC status. This message is only issued once for a given start of the system. However, the "wait for input" behavior continues. ystem. However, the "wait.
  • CASTM5039I IMS TM process generated a dump to dump dataset dump-dataset
    A dump of the IMS TM process was requested and this dump was generated to the dump-dataset dump dataset.
Parent topic: CASTM Error Messages


CASTM5020S IMS TM Message Q version mismatch. Disk version is version

The message queue disk file is written in a format that is not suppored by this version of IMS TM. The version on disk appears to be version.
System Action:
IMS TM message queue is cold started. The problem queue is renamed to .bak.
Resolution:
Upgrade the message queue file if a utility is available or continue with the cold start of the message queue.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5021S IMS TM Message Q upgrade or cold start is required. Version: version

The message queue disk file is written in a format that is not suppored by this version of IMS TM. The current TM software version is version.
System Action:
IMS TM support is disabled.
Resolution:
Upgrade the message queue file if a utility is available or cold start the IMS Message Queue.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5022E Signon ID error: user ID user-identifier, group security-group at LU logical-unit

A user tried to signon using TM with ID user-identifier, specifying secruity group security-group from logical unit logical-unit. The signon was rejected as an ID error.
System Action:
The user signon is rejected.
Resolution:
Present valid credentials.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5023E Signon password error: user ID user-identifier, group security-group at LU logical-unit

A user tried to signon using TM with ID user-identifier, specifying secruity group security-group from logical unit logical-unit. The signon was rejected as a password error.
System Action:
The user signon is rejected.
Resolution:
Present valid credentials.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5024S Signon SAF error: user ID user-identifier, group security-group at LU logical-unit

A user tried to signon using TM with ID user-identifier, specifying secruity group security-group from logical unit logical-unit. The signon was rejected because of a SAF error. An unexpected external security system error was returned on the verify call.
System Action:
The user signon is rejected.
Resolution:
Notify security personell.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5025E Signon ID revoked: user ID user-identifier, group security-group at LU logical-unit

A user tried to signon using TM with ID user-identifier, specifying secruity group security-group from logical unit logical-unit. The signon was rejected because the ID has been revoked.
System Action:
The user signon is rejected.
Resolution:
Notify security personell.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5026E Signon password expired: user ID user-identifier, group security-group at LU logical-unit

A user tried to signon using TM with ID user-identifier, specifying secruity group security-group from logical unit logical-unit. The signon was rejected because the password has expired.
System Action:
The user signon is rejected.
Resolution:
Retry and supply a new password.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5027I IMS TM MFS is operating with character attribute bias

Unless otherwise specified in the TRANSACT macro, Message Format Services will operate on ASCII application supplied attributes as character attributes.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5028I IMS TM MFS is operating with binary attribute bias

Unless otherwise specified in the TRANSACT macro, Message Format Services will operate on ASCII application supplied attributes as binary attributes.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5029I IMS TM MFS ASCII null character system bias is null-character

Unless otherwise specified in the TRANSACT macro, Message Format Services will operate on ASCII application supplied messages using null-character as the MFS null character.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5030I IMS TM resource definitions and statistics cold started

Resource definitions and statistics from the previous run's keypoint have been discarded.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5031I IMS TM resource definitions restored, statistics cold started

Resource statistics from previous run's keypoint have been discarded. The resource definitions have been restored to the state recorded in the last keypoint.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5032I IMS TM resource definitions and statistics restored

The resource definitions and statistics have been restored to the state recorded in the last keypoint.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5033S IMS TM message queue corruption detected: block queue-file-block

The IMS TM message queue disk storage is corrupted.
System Action:
System attempts to correct error.
Resolution:
Asses system damage, stop and repair system if necessary.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5034S IMS TM message queue segment error: block queue-file-block; segment segment-number

The IMS TM message queue disk storage is corrupted.
System Action:
System attempts to correct error.
Resolution:
Asses system damage, stop and repair system if necessary.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5035E IMS MPP ABEND; Transaction transaction stopped

Transaction transaction has been stopped because of the message processing program experienced an ABEND.
System Action:
Transaction aborted, protected data is rolled back.
Resolution:
Correct the MPP problem and retry.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5036S IMS TM Message Queue structure problem encountered

The message queue disk file format is not recognized that is not suppored by this version of IMS TM. The version on disk appears to be .
System Action:
IMS TM support is cold started.
Resolution:
Recover message queue file if possible or continue the cold start.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5037I IMS TM old Queue File: queue-file-name

queue-file-name is the name of the old IMS Message Queues file that was replaced as a part of cold starting the message queues.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5038I IMS transaction transaction marked as implicit wait for input

transaction does further GU operations to the message queue after it has recieved a QC status. This message is only issued once for a given start of the system. However, the "wait for input" behavior continues. ystem. However, the "wait.
System Action:
For GU message queue calls issued after recieving a QC, this transaction will wait until a new transaction is available.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5039I IMS TM process generated a dump to dump dataset dump-dataset

A dump of the IMS TM process was requested and this dump was generated to the dump-dataset dump dataset.
System Action:
The IMS TM process produceses a dump.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5040 - CASTM5052

  • CASTM5040I IMS TM Message Queue File flush requests disabled
    Flush operations for this file are bypassed. When this mode of operation is used, file integrity will not be assured in the event of a system failure.
  • CASTM5041I IMS TM Message Queue File flush requests aggregate time aggregation-minimum milliseconds
    A flush aggregation span of aggregation-minimum millisecond is now effective. This will cause flush requests to be accumulated during the specified interval and a single flush issued for all requests.
  • CASTM5042I IMS TM Message Queue File flush requests aggregate disabled
    Fush aggregation has been dynamically disabled.
  • CASTM5043I IMS TM Message Queue File flush enabled
    Flush operations for this file are now enabled.
  • CASTM5044I IMS TM exit programs loaded:
    The named modules have been loaded and associated with their related exit points.
  • CASTM5045S IMS Message Formatting Services local memory allocation error.
    Message Formatting Services has terminated attempting to allocate local storage.
  • CASTM5046W IMS TM MFS segment exit program could not be called
    The requested exit program could not be called because of a local memory allocation problem.
  • CASTM5047I DFSNDMI0 succeeded transaction=transaction PSB=PSB destination=destination
    The application program associated with PSB PSB terminated abnormally while processing transaction transaction and the nondiscardable messages user exit interface (DFSNDMI0) succeeded in requeuing the input message to destination destination.
  • CASTM5048E IMS TM rejected printer printer-name because it is not authorized
    The printer printer-name tried to connect to ES IMS TM but, because it is not recognized by security, the connection has been rejected.
  • CASTM5049E IMS TM rejected terminal printer-name because it is not authorized
    The terminal printer-name tried to connect to ES IMS TM but, because it is not recognized by security, the connection has been rejected.
  • CASTM5050W IMS TM Message Queue file nearly full
    The file is approaching an out-of-space condition.
  • CASTM5051E IMS TM Message Queue file out of space
    The file has reached the space limitations specified by the server configuration.
  • CASTM5052E IMS TM response mode transaction transaction-name terminated without a response
    The response mode transaction transaction-name terminated without generating a response. This transaction is the target of a transaction switch so the input must be handled by the non-discardable message exit. The default will be to move the input message to the class zero queue and stop the transaction. A subsiquent message will be issued if the transaction is stopped.
Parent topic: CASTM Error Messages


CASTM5040I IMS TM Message Queue File flush requests disabled

Flush operations for this file are bypassed. When this mode of operation is used, file integrity will not be assured in the event of a system failure.
Module:
castmc
Destination:
Console
Parent topic: CASTM5040 - CASTM5052


CASTM5041I IMS TM Message Queue File flush requests aggregate time aggregation-minimum milliseconds

A flush aggregation span of aggregation-minimum millisecond is now effective. This will cause flush requests to be accumulated during the specified interval and a single flush issued for all requests.
Module:
castmc
Destination:
Console
Parent topic: CASTM5040 - CASTM5052


CASTM5042I IMS TM Message Queue File flush requests aggregate disabled

Fush aggregation has been dynamically disabled.
Module:
castmc
Destination:
Console
Parent topic: CASTM5040 - CASTM5052


CASTM5043I IMS TM Message Queue File flush enabled

Flush operations for this file are now enabled.
Module:
castmc
Destination:
Console
Parent topic: CASTM5040 - CASTM5052


CASTM5044I IMS TM exit programs loaded:

The named modules have been loaded and associated with their related exit points.
Module:
castmc
Destination:
Console
Parent topic: CASTM5040 - CASTM5052


CASTM5045S IMS Message Formatting Services local memory allocation error.

Message Formatting Services has terminated attempting to allocate local storage.
System Action:
The process terminates normally.
Resolution:
Correct the error and restart the system.
Module:
casmfs
Destination:
System Console and standard error.
Parent topic: CASTM5040 - CASTM5052


CASTM5046W IMS TM MFS segment exit program could not be called

The requested exit program could not be called because of a local memory allocation problem.
System Action:
The exit is not called.
Resolution:
Correct the error and restart the system.
Module:
casmfs
Destination:
Console
Parent topic: CASTM5040 - CASTM5052


CASTM5047I DFSNDMI0 succeeded transaction=transaction PSB=PSB destination=destination

The application program associated with PSB PSB terminated abnormally while processing transaction transaction and the nondiscardable messages user exit interface (DFSNDMI0) succeeded in requeuing the input message to destination destination.
System Action:
The input message is requeued to the destination.
Module:
castmc
Destination:
Console
Parent topic: CASTM5040 - CASTM5052


CASTM5048E IMS TM rejected printer printer-name because it is not authorized

The printer printer-name tried to connect to ES IMS TM but, because it is not recognized by security, the connection has been rejected.
System Action:
The printer is disconnected.
Resolution:
Authorize the printer and retry the connection.
Module:
castmc
Destination:
Console, Printer
Parent topic: CASTM5040 - CASTM5052


CASTM5049E IMS TM rejected terminal printer-name because it is not authorized

The terminal printer-name tried to connect to ES IMS TM but, because it is not recognized by security, the connection has been rejected.
System Action:
The printer is disconnected.
Resolution:
Authorize the printer and retry the connection.
Module:
castmc
Destination:
Console, Printer
Parent topic: CASTM5040 - CASTM5052


CASTM5050W IMS TM Message Queue file nearly full

The file is approaching an out-of-space condition.
Resolution:
Consider either reclaiming queue space by using the /DEQ command, and/or increasing the number of Maximum blocks available for the message queue in the server's configuration.
Module:
castmc
Destination:
Console
Parent topic: CASTM5040 - CASTM5052


CASTM5051E IMS TM Message Queue file out of space

The file has reached the space limitations specified by the server configuration.
Resolution:
Restart the server, and consider increasing the number of Maximum blocks available for the message queue in the server's configuration.
Module:
castmc
Destination:
Console
Parent topic: CASTM5040 - CASTM5052


CASTM5052E IMS TM response mode transaction transaction-name terminated without a response

The response mode transaction transaction-name terminated without generating a response. This transaction is the target of a transaction switch so the input must be handled by the non-discardable message exit. The default will be to move the input message to the class zero queue and stop the transaction. A subsiquent message will be issued if the transaction is stopped.
System Action:
Stop the transaction and suspend the input message.
Resolution:
Correct the transaction.
Module:
castmc
Destination:
Console
Parent topic: CASTM5040 - CASTM5052


CASTS Error Messages

Message | Description | Resolution
CASTS0001I ES TSC Service Process restart in progress | The ES TSC Service process has been restarted and recovery operations are in progress | None
CASTS0002I ES TSC Service Process initialization complete | The ES TSC Service Process has completed initialization. | None
CASTS0003I ES TSC Service Process termination started | The ES TSC Service Process is terminating. | None
CASTS0004S ES TSC Service Process registration failed, reason = reason-code | The ES TSC Service Process failed registration. | Report failure to Micro Focus
CASTS0005I ES TSC Service Process termination complete# | The ES TSC Service Process has terminated. | None
CASTS0006I tsc-control-message | The ES TSC Service Process issued a message. | Action the message
CASTS0007I ES TSC Service Process initialization started | The server ES TSC Service Process initialization has started. | None
CASTS0008S ES TSC Service Process is not running in multi-threaded mode | The ES TSC Service Process has not started with the required underlying thread support. | Report failure to Micro Focus
CASTS0009W TS queue queue-number inconsistent end at location queue-file-block; should be expected-file-block. | The ES TSC process has encountered a problem with temporary storage queue queue-number. The reported block (expected-file-block) is the expected end and it may be orphaned. | Verify that important data has not been lost.
CASTS0010W TS queue queue-number invalid chain start at location queue-file-block. | The ES TSC process has encountered a problem with temporary storage queuequeue-number. The reported block is not of the proper TS data type. | The reported block is the expected first in the chain.
CASTS0011W TS queue queue-number invalid chain next reference queue-file-block from block next-file-block. | The ES TSC process has encountered a problem with temporary storage queuequeue-number. The reported block (queue-file-block) has a chain next pointer of next-file-block which is out of range. | The reported block is the expected first in the chain. Verify that important data has not been lost.
CASTS0018W TS queue queue-number invalid segment referenced segment-reference from block queue-file-block. | The ES TSC process has encountered a problem with temporary storage queue queue-number. The reported block (queue-file-block) has a chain next pointer which points to an invalid segment in the message queue file. | The reported block is the expected first in the chain. Verify that important data has not been lost.
CASTS5012S ES TSC Log and Intra-Partition TS/TD init failed. Reason (reason-code) The IMS TM Control Process failed to initialize its message queues. The reason code is one of the following and may be followed by a ":" and RTS file IO error code.
  • 0 - Queue file anchor array size mismatch
  • 1 - Failure reading queue file header
  • 2 - Failure during create of the queue file
  • 3 - Failure writing the queue file headers
  • 4 - Failure allocating queue file buffers
  • 5 - Failure allocating storage for the free space array
  • 6 - Failure writing the free space array
  • 7 - Failure reading the free space array
  • 8 - Queue file header record size mismatch
  • 9 - Queue file record size mismatch
  • A - Queue file record block number mismatch
Correct the message queues configuration and restart the Enterprise Server
CASTS5013I ES TSC Log and Intra-Partition TS/TD cold started | The ES TS/TD repository has been cold started. No old data has been retained. | None
CASTS5014W ES TSC Log and Intra-Partition TS/TD not properly closed previously | The ES TS/TD repository was not properly closed the last time it was accessed. | None
CASTS5015I ES TSC Log and Intra-Partition TS/TD: queue-file-name | queue-file-name is the name of the IMS Message Queues file that will be used during this execution of ES. | None
CASTS5016I ES TSC Log and Intra-Partition TS/TD File size: block-count blocks (size bytes) | The allocated block count for the message queues is block-count. These blocks are composed of a block header plus 254 segments, each consisting of 244 bytes of queue data. The total file size is size bytes. | None
CASTS5017I ES TSC Log and Intra-Partition TS/TD running with queue-buffer-count buffers of buffer-size bytes each# | queue-buffer-count buffers are allocated for the message queues use during this execution of ES. Each buffer is buffer-size bytes in length. | None
CASTS5020S ES TSC Log and Intra-Partition TS/TD version mismatch. Disk version is version | The message queue disk file is written in a format that is not supported by this version of IMS TM. The version on disk appears to be version. | Upgrade the message queue file if a utility is available or cold start the IMS Message Queue
CASTS5021S ES TSC Log and Intra-Partition TS/TD upgrade or cold start is required. Version: version | The message queue disk file is written in a format that is not supported by this version of ES. The current TM software version is version. | Or continue with the current cold start.
CASTS5033S ES TSC Log and Intra-Partition TS/TD corruption detected: block queue-file-block | The ES TS/TD repository is corrupted. | Assess system damage, stop and repair system if necessary
CASTS5034S ES TSC Log and Intra-Partition TS/TD segment error: block queue-file-block; segment segment-number | The ES TS/TD repository disk storage is corrupted. | Assess system damage, stop and repair system if necessary
CASTS5036S ES TSC Log and Intra-Partition TS/TD structure problem encountered | The message queue disk file structure is not recognized. | Recover or cold start the TS/TD Repository.
CASTS5037I ES TSC old TS/TD File: Log and TS/TD repository name | Log and TS/TD repository name is the old ES Log and TS/TD repository that was replaced as a part of cold starting the repository. | None
CASTS5038I Cannot open HSF file because the file is locked. File: filename | The filename cannot be opened because the file is locked | Close any programs that have a lock on filename
CASTS5040I ES TSC Log and Intra-Partition TS/TD flush operations disabled | Flush operations for this file are bypassed. When this mode of operation is used, file integrity will not be assured in the event of a system failure. | None
CASTS5041I ES TSC Log and Intra-Partition TS/TD flush requests aggregate time aggregation-minimum milliseconds | A flush aggregation span of aggregation-minimum millisecond is now effective. This will cause flush requests to be accumulated during the specified interval and a single flush issued for all requests. | None
CASTS5042I ES TSC Log and Intra-Partition TS/TD flush requests aggregate disabled | Fush aggregation has been dynamically disabled | None
CASTS5043I ES TSC Log and Intra-Partition TS/TD flush requests enabled | Flush operations for this file are now enabled | None
CASTS5050W ES TSC Log and Intra-Partition TS/TD file nearly full | The file is approaching an out-of-space condition. | Report failure to Micro Focus
CASTS5051E ES TSC Log and Intra-Partition TS/TD file out of space | The file has reached its space limitations. | Report failure to Micro Focus
Parent topic: Enterprise Server Error Messages


CASXB Error Messages

  • CASXB0002 - CASXB0019
  • CASXB0020 - CASXB0039
  • CASXB0040 - CASXB0059
  • CASXB0060 - CASXB0076
Parent topic: Enterprise Server Error Messages


CASXB0002 - CASXB0019

  • CASXB0002S Expected DFHMSD TYPE=FINAL - remainder of source discarded
    Either the end of the input file was found without a closing DFHMSD TYPE=FINAL macro, or a second DFHMSD macro was found, but did not contain the TYPE=FINAL argument. The latter can be caused by coding multiple mapsets in the same .bms source file, which is not allowed by this system.
  • CASXB0003E Unrecognized verb "<verb>" - remainder of macro discarded
    An unknown verb was found in the BMS source deck. Known verbs include DFHMSD, DFHMDI, DFHMDF and END. TITLE, EJECT, SPACE, PRINT verbs are parsed and ignored without warning.
  • CASXB0004W Unrecognized parameter "<parm-name>" ignored
    An unknown parameter was found for the given macro/verb.
  • CASXB0005E Illegal value "<parm-value>" rejected
    An illegal value was found for a parameter. The value could be syntactically invalid, out of range, not in the parameter's domain, not numeric (if required to be).
  • CASXB0006E POS=<position> is outside defined map size
    The DFHMDF POS= value places the field outside of the defined map boundaries. POS can be expressed as an offset from the top of the map, i.e. POS=nnn, or as a row-column value, i.e., POS=(row,col). Row and Col values must be greater than zero.
  • CASXB0007E Invalid PICIN/PICOUT value
    The PICIN or PICOUT value is not a valid BMS picture clause.
  • CASXB0008W PICIN/PICOUT lengths unequal - using the shorter one
    Both PICIN and PICOUT are coded, but the represented data lengths are not equal.
  • CASXB0009W value has an odd number of hex-digits
    Hexadecimal literals must contain an even number of characters from the set '0123456789abcdef'.
  • CASXB0010E Hex string can only contain characters 0-9 and A-F
    Hexadecimal literals can only contain the characters from the set '0123456789abcdef'.
  • CASXB0011E DBCS string is not even
    Double-byte (DBCS) literals must contain an even number of tokens, since each pair represents a character.
  • CASXB0012E Length must be even
    When PS=8, LENGTH= must be even.
  • CASXB0013E SOSI=YES cannot be specified with PS=8
    When PS=8 (pure DBCS symbols), fields may not contain mixed SBCS/DBCS literals delimited using SOSI characters.
  • CASXB0014E PS=8 requires INITIAL/XINIT to be even
    When PS=8 (pure DBCS symbols), the initial value (INITIAL or XINIT) should contain an even number of characters, each pair representing a DBCS character.
  • CASXB0015E PS=8 requires DBCS characters in INITIAL/XINIT
    When PS=8 (pure DBCS symbols), the initial value (INITIAL or XINIT) should contain only DBCS characters. Found at least one SBCS character.
  • CASXB0016E Only one INITIAL/XINIT/GINIT allowed
    INITIAL, XINIT or GINIT are mutually exclusive.
  • CASXB0017E GINIT specified without PS=8
    PS=8 (pure DBCS symbols) is required when specifying GINIT (DBCS initial value).
  • CASXB0018E SIZE=<size-spec> exceeds configured desktop size
    The specified map <size-spec> (DFHMDI SIZE) is larger than the painter's configured desktop size.
  • CASXB0019E Closing ')' not found - value rejected
    A multi-valued parameter's value contained an opening parenthesis '(', but not a closing parenthesis ')'.
Parent topic: CASXB Error Messages


CASXB0002S Expected DFHMSD TYPE=FINAL - remainder of source discarded

Either the end of the input file was found without a closing DFHMSD TYPE=FINAL macro, or a second DFHMSD macro was found, but did not contain the TYPE=FINAL argument. The latter can be caused by coding multiple mapsets in the same .bms source file, which is not allowed by this system.
System Action:
Loading of the BMS file is aborted.
Resolution:
Verify that your source file contains one and only one closing DFHMDF macro as the last source statement preceding the END statement.
Module:
scrload
Destination:
STDOUT, .TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0003E Unrecognized verb "<verb>" - remainder of macro discarded

An unknown verb was found in the BMS source deck. Known verbs include DFHMSD, DFHMDI, DFHMDF and END. TITLE, EJECT, SPACE, PRINT verbs are parsed and ignored without warning.
System Action:
The remainder of the macro (including continued lines) is ignored.
Resolution:
Correct or comment-out the offending macro.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0004W Unrecognized parameter "<parm-name>" ignored

An unknown parameter was found for the given macro/verb.
System Action:
The parameter and its value are discarded.
Resolution:
Correct the spelling of the offending parameter.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0005E Illegal value "<parm-value>" rejected

An illegal value was found for a parameter. The value could be syntactically invalid, out of range, not in the parameter's domain, not numeric (if required to be).
System Action:
The value is discarded, and a default value is used.
Resolution:
Verify the spelling and of the offending parameter value. Consult your CICS Applications Programmer Reference Manual for rules governing the parameter.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0006E POS=<position> is outside defined map size

The DFHMDF POS= value places the field outside of the defined map boundaries. POS can be expressed as an offset from the top of the map, i.e. POS=nnn, or as a row-column value, i.e., POS=(row,col). Row and Col values must be greater than zero.
System Action:
The value is discarded, and a default value of (1,1) is used.
Resolution:
Code a value within the bounds of the map.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0007E Invalid PICIN/PICOUT value

The PICIN or PICOUT value is not a valid BMS picture clause.
System Action:
A default picture of X(length) is used.
Resolution:
Code a valid picture clause. Consult your CICS Applications Programmer Reference Manual for rules governing this parameter.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0008W PICIN/PICOUT lengths unequal - using the shorter one

Both PICIN and PICOUT are coded, but the represented data lengths are not equal.
System Action:
The shorter picture clause is used for both.
Resolution:
Verify the PICIN and PICOUT clauses, and ensure they are compatible.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0009W value has an odd number of hex-digits

Hexadecimal literals must contain an even number of characters from the set '0123456789abcdef'.
System Action:
The trailing nibble is truncated, and the truncated value is used.
Resolution:
Examine the hex literal for a typographical error.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0010E Hex string can only contain characters 0-9 and A-F

Hexadecimal literals can only contain the characters from the set '0123456789abcdef'.
System Action:
The hex string is discarded, and a default value is used (usually low-values or spaces).
Resolution:
Examine the hex literal for a typographical error.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0011E DBCS string is not even

Double-byte (DBCS) literals must contain an even number of tokens, since each pair represents a character.
System Action:
The trailing nibble (half-char) is truncated.
Resolution:
Examine the DBCS literal for a typographical error.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0012E Length must be even

When PS=8, LENGTH= must be even.
System Action:
None. Values reluctantly accepted.
Resolution:
Adjust the LENGTH= specification (or PICIN/PICOUT if LENGTH= is omitted) to an even value.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0013E SOSI=YES cannot be specified with PS=8

When PS=8 (pure DBCS symbols), fields may not contain mixed SBCS/DBCS literals delimited using SOSI characters.
System Action:
None. Values reluctantly accepted.
Resolution:
Choose between using PS=8 and SOSI.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0014E PS=8 requires INITIAL/XINIT to be even

When PS=8 (pure DBCS symbols), the initial value (INITIAL or XINIT) should contain an even number of characters, each pair representing a DBCS character.
System Action:
The trailing char (half DBCS-char) will be truncated.
Resolution:
Examine the DBCS literal for a typographical error.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0015E PS=8 requires DBCS characters in INITIAL/XINIT

When PS=8 (pure DBCS symbols), the initial value (INITIAL or XINIT) should contain only DBCS characters. Found at least one SBCS character.
System Action:
None. The value is accepted as specified.
Resolution:
Examine the INITIAL/XINIT value for a non-DBCS character.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0016E Only one INITIAL/XINIT/GINIT allowed

INITIAL, XINIT or GINIT are mutually exclusive.
System Action:
This parameter is discarded.
Resolution:
Adjust the BMS to contain only one initial value parameter, (INITIAL, XINIT or GINIT).
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0017E GINIT specified without PS=8

PS=8 (pure DBCS symbols) is required when specifying GINIT (DBCS initial value).
System Action:
None. The value is accepted as specified.
Resolution:
Specify PS=8, or change the initial value parameter to INITIAL or XINIT.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0018E SIZE=<size-spec> exceeds configured desktop size

The specified map <size-spec> (DFHMDI SIZE) is larger than the painter's configured desktop size.
System Action:
The map is truncated to the width/height of the configured desktop size.
Resolution:
Specify a smaller map size (DFHMDI SIZE), or adjust the desktop size in the painter's configuration.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0019E Closing ')' not found - value rejected

A multi-valued parameter's value contained an opening parenthesis '(', but not a closing parenthesis ')'.
System Action:
The entire multi-value string is taken as null.
Resolution:
Check for balanced parentheses around multi-valued parameters.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0002 - CASXB0019


CASXB0020 - CASXB0039

  • CASXB0020W Extra values after ')' ignored
    A multi-valued parameter value contained extraneous data either after the closing parenthesis, or after the maximum number of allowed values for that parameter.
  • CASXB0021E Quoted value expected
    An unquoted value was found for a parameter that requires its value be enclosed in quotes (').
  • CASXB0022E Repeated field attributes different - repeat terminated
    obsolete.
  • CASXB0023E Repeated group instance is invalid - group closed
    The SDF-type repeated group specification cannot be processed. Either (1) a second or later group instance does not contain the same member fields as the first instance, or (2) a third or later instance does not repeat symmetrically in the same direction as the second instance.
  • CASXB0024E Too many fields in group - group closed
    SDF-type group definitions are currently limited to 50 member fields for each group instance. In command line mode, this includes text fields (unnamed DFHMDF macros).
  • CASXB0025E Field cannot belong to an SDF group and BMS subfield group
    BMS subfields (defined using the GRPNAME= parameter) cannot be defined as members of an SDF-type group. The system stores both in similar ways, and defining a field as a member of both causes conflicts.
  • CASXB0026W BMS subfield's attributes differ from the first subfield
    obsolete.
  • CASXB0027W Quoted literal must resume in column 16
    Continuation cards can resume in any column 2 through 16, EXCEPT quoted literals, which must resume in column 16.
  • CASXB0028E Continued card must resume in column 2-16
    Continuation cards can resume in any column 2 through 16, EXCEPT quoted literals, which must resume in column 16. A valid continuation card was not found.
  • CASXB0029W Name "<label>" exceeds 7 characters - truncated
    Names (labels) for mapsets and maps cannot exceed 7 characters.
  • CASXB0030E Command/macro-id not found following label text
    A command or macro-id was not found on the first line of the statement/macro definition. Each statement or.
  • CASXB0031E String "<text>..." exceeds 256 characters - rejecting macro
    The string or token beginning with <text> exceeded the maximum 256 characters.
  • CASXB0032W Argument "<text-string>" folded to uppercase
    The argument <text-string> contained lowercase characters, which is incompatible with some host assemblers. This does not apply to literal strings enclosed in quotes.
  • CASXB0033W Host compatibility: Blank card found
    A blank input card was found. This is incompatible with some host assemblers.
  • CASXB0034I Processing Map <map-name>
    This is a processing status display that appears for each <map-name> as it is encountered in the BMS source file. It is only displayed when verbose-mode is specified (/v).
  • CASXB0035W Warning: MCO forces TIOAPFX=YES on MOD/CPY generation
    TIOAPFX=NO was either specified or implied for the current map. The MCO/MTS runtime assumes TIOAPFX=YES when communicating with user dsects, so it is forced when a dsect (copybook) and load module (.MOD) are generated. BMS regenerated from the screen painter is not affected, in order to maintain portability with your host settings. However, this may prevent you from porting the generated copybook to your host system.
  • CASXB0036S Error: Unable to open .trl file, status=<file-status>
    <file-status> was returned from the open request for the translator listing (.trl) file. This file is created in the same directory as the input source file, but with a .trl extension.
  • CASXB0037S Unexpected I/O error on input file, status=<file-status>
    An unexpected <file-status> was returned from an I/O request against the specified file.
  • CASXB0038S Unexpected heap error, status=<heap-file-status>
    An unexpected <heap-file-status> was returned from an internal heap I/O request.
  • CASXB0039S Unexpected error creating map, GL-status=<internal-status>
    An unexpected <internal-status> was received when rendering the map in the internal database.
Parent topic: CASXB Error Messages


CASXB0020W Extra values after ')' ignored

A multi-valued parameter value contained extraneous data either after the closing parenthesis, or after the maximum number of allowed values for that parameter.
System Action:
The extraneous data is discarded.
Resolution:
Check for extraneous data following any multi-valued parameters.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0020 - CASXB0039


CASXB0021E Quoted value expected

An unquoted value was found for a parameter that requires its value be enclosed in quotes (').
System Action:
The value is discarded.
Resolution:
Enclose the parameter value in quotes (').
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0020 - CASXB0039


CASXB0022E Repeated field attributes different - repeat terminated

obsolete.
System Action:
n/a.
Resolution:
n/a.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0020 - CASXB0039


CASXB0023E Repeated group instance is invalid - group closed

The SDF-type repeated group specification cannot be processed. Either (1) a second or later group instance does not contain the same member fields as the first instance, or (2) a third or later instance does not repeat symmetrically in the same direction as the second instance.
System Action:
The group definition is truncated. Remaining fields will be created as ordinary (ungrouped) fields.
Resolution:
Correct the sequence of named DFHMDF macros (fields) that constitute the group, ensuring that they are balanced and that all group instances repeat in the same direction.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0020 - CASXB0039


CASXB0024E Too many fields in group - group closed

SDF-type group definitions are currently limited to 50 member fields for each group instance. In command line mode, this includes text fields (unnamed DFHMDF macros).
System Action:
The group definition is discarded. The fields will be created as ordinary (ungrouped) fields. This message will likely be produced many times in sequence, as macros for subsequent group instances are encountered.
Resolution:
Specify fewer fields in each instance of the group. Consider combining text macros, or splitting the group into two smaller groups.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0020 - CASXB0039


CASXB0025E Field cannot belong to an SDF group and BMS subfield group

BMS subfields (defined using the GRPNAME= parameter) cannot be defined as members of an SDF-type group. The system stores both in similar ways, and defining a field as a member of both causes conflicts.
System Action:
The group definition is truncated. Remaining fields will be created as ordinary (ungrouped) fields.
Resolution:
Remove the compound field from the SDF-type group definition, or change the compound field to several simple fields.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0020 - CASXB0039


CASXB0026W BMS subfield's attributes differ from the first subfield

obsolete.
System Action:
n/a.
Resolution:
n/a.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0020 - CASXB0039


CASXB0027W Quoted literal must resume in column 16

Continuation cards can resume in any column 2 through 16, EXCEPT quoted literals, which must resume in column 16.
System Action:
Text in columns 1-15 is discarded, and the remainder of the card is interpreted as the continuation.
Resolution:
Check that the preceding card did not inadvertently contain text in column 72, as it will cause the current card to be treated as a continuation. Check that the contents of the continuation card begins in column 16.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0020 - CASXB0039


CASXB0028E Continued card must resume in column 2-16

Continuation cards can resume in any column 2 through 16, EXCEPT quoted literals, which must resume in column 16. A valid continuation card was not found.
System Action:
The remainder of the macro, if any, is discarded.
Resolution:
Check that the preceding card did not inadvertently contain a continuation character in column 72.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0020 - CASXB0039


CASXB0029W Name "<label>" exceeds 7 characters - truncated

Names (labels) for mapsets and maps cannot exceed 7 characters.
System Action:
The name is truncated at 7 characters.
Resolution:
Specify a shorter name (label) for the mapset or map.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0020 - CASXB0039


CASXB0030E Command/macro-id not found following label text

A command or macro-id was not found on the first line of the statement/macro definition. Each statement or.
System Action:
The remainder of the macro, including any continued lines, is discarded.
Resolution:
macro should begin with an optional label in column 1, followed by at least one space, followed by the command or macro-id. The command/macro-id can be continued onto a subsequent card. Check for a typographical error, and ensure that the command/macro-id begins on the first line of the macro statement.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0020 - CASXB0039


CASXB0031E String "<text>..." exceeds 256 characters - rejecting macro

The string or token beginning with <text> exceeded the maximum 256 characters.
System Action:
The remainder of the macro, including any continued lines, is discarded.
Resolution:
Check for unbalanced parentheses, unbalanced quotes, or an excessively long string of characters.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0020 - CASXB0039


CASXB0032W Argument "<text-string>" folded to uppercase

The argument <text-string> contained lowercase characters, which is incompatible with some host assemblers. This does not apply to literal strings enclosed in quotes.
System Action:
The value is folded to uppercase, and processing continues.
Resolution:
If your host assembler does not support lowercase source code, adjust the value of <text-string>. Otherwise, ignore this warning.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0020 - CASXB0039


CASXB0033W Host compatibility: Blank card found

A blank input card was found. This is incompatible with some host assemblers.
System Action:
The card is ignored, and processing continues.
Resolution:
If your host assembler does not allow blank input cards, remove it. Otherwise, ignore this warning.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0020 - CASXB0039


CASXB0034I Processing Map <map-name>

This is a processing status display that appears for each <map-name> as it is encountered in the BMS source file. It is only displayed when verbose-mode is specified (/v).
System Action:
None. Processing continues.
Resolution:
None.
Module:
scrload
Destination:
stdout
Parent topic: CASXB0020 - CASXB0039


CASXB0035W Warning: MCO forces TIOAPFX=YES on MOD/CPY generation

TIOAPFX=NO was either specified or implied for the current map. The MCO/MTS runtime assumes TIOAPFX=YES when communicating with user dsects, so it is forced when a dsect (copybook) and load module (.MOD) are generated. BMS regenerated from the screen painter is not affected, in order to maintain portability with your host settings. However, this may prevent you from porting the generated copybook to your host system.
System Action:
TIOAPFX=YES is forced in generated copybooks and mapset load modules.
Resolution:
If this message appears, you must alter the generated copybook after porting it to your host system by removing the 12-byte filler (the TIOA prefix) from the head of each map's dsect.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0020 - CASXB0039


CASXB0036S Error: Unable to open .trl file, status=<file-status>

<file-status> was returned from the open request for the translator listing (.trl) file. This file is created in the same directory as the input source file, but with a .trl extension.
System Action:
Loading of the input file is terminated.
Resolution:
Investigate and correct the cause of the error using the <file-status>.
Module:
scrload
Destination:
stdout
Parent topic: CASXB0020 - CASXB0039


CASXB0037S Unexpected I/O error on input file, status=<file-status>

An unexpected <file-status> was returned from an I/O request against the specified file.
System Action:
Loading of the input file is terminated.
Resolution:
Investigate and correct the cause of the <file-status>.
Module:
scrload
Destination:
stdout
Parent topic: CASXB0020 - CASXB0039


CASXB0038S Unexpected heap error, status=<heap-file-status>

An unexpected <heap-file-status> was returned from an internal heap I/O request.
System Action:
Loading of the input file is terminated.
Resolution:
Investigate and correct the cause of the <heap-file-status>. If this is an extremely large mapset, try setting COBSW=+P3 to increase heap capacity.
Module:
scrload
Destination:
stdout
Parent topic: CASXB0020 - CASXB0039


CASXB0039S Unexpected error creating map, GL-status=<internal-status>

An unexpected <internal-status> was received when rendering the map in the internal database.
System Action:
Loading of the input file is terminated.
Resolution:
Contact product support with the status code and the input file being used.
Module:
scrload
Destination:
stdout
Parent topic: CASXB0020 - CASXB0039


CASXB0040 - CASXB0059

  • CASXB0040S The input file is not a valid MF Forms .frm file
    The input file has an .frm (upper or lowercase) extension, but is not a valid Micro Focus Forms file. Some compatibility exists for migrating Micro Focus Forms files into this screen painter's native format, though some incompatibility does exist.
  • CASXB0041W No comma after last parm, continuation cards are comments
    This card is continued, but the last parameter was not followed by a comma. Therefore, continued cards are a continuation of comment text.
  • CASXB0042W Expected another parameter following the last comma
    The last parameter on this card was followed by a comma, indicating that more parameters would follow. However, none were found.
  • CASXB0043S The input file is not a valid MF Screens .srn file
    The input file has an .srn (upper or lowercase) extension, but is not a valid Micro Focus Screens file. Some compatibility exists for migrating Micro Focus Screens files into this screen painter's native format, though some incompatibility does exist.
  • CASXB0044E Repeated fields must be vertically or horizontally adjacent
    obsolete.
  • CASXB0045E Repeated field/group is not symmetric/balanced
    obsolete.
  • CASXB0046I No DFHMDI SIZE arg. Using configured default map size
    This map does not have an explicit SIZE parameter, which will cause it to be displayed differently on different display sizes. In order to render the map in the painter, the painter's default map size (configurable) is arbitrarily used. Note that any fields must be expressed as POS=offset instead of POS=(row,col). When regenerating BMS from the painter, if a map size is not specified, the generated field macros will be expressed as POS=nnnn instead of POS=(row,col).
  • CASXB0047W POS=offset should be used when DFHMDI SIZE= is omitted
    This map was defined without an explicit SIZE= argument, so specifying this field with POS=(row,col) may not be rendered as expected.
  • CASXB0048W POS=(row,col) should be used when DFHMDI SIZE= is specified
    This map was defined with an explicit SIZE= argument, so specifying this field with POS=nnnn is improper (though allowed).
  • CASXB0049W CTRL ignored... Already specified in DFHMSD macro
    The CTRL parameter was already specified in the DFHMSD macro. Contrary to the CICS 3.3 Applications Programming Reference Manual, and contrary to normal inheritance rules, this value does not supersede the mapset specification.
  • CASXB0050W ATTRB=IC specified for a protected field. Accepted.
    A protected field (ASKIP or PROT) wouldn't normally have the cursor placed in it, though it is allowed, since the application may dynamically change the field to unprotected before the map is sent.
  • CASXB0051E Repeated fields must have same LENGTH, PICIN and PICOUT
    Repeated field (array) instances must yield compatible dsect definitions in order to be rendered into an array. Although some properties can differ, the LENGTH, PICIN and PICOUT values must be identical. The repeated field instance was detected by finding that the previous named field had the same alternate-name in its comment (SDF-mode or ADVS-mode only).
  • CASXB0052W Field overlaps another with MODE=IN/INOUT
    Overlapping input fields can cause ambiguity at runtime when rendering user input from the 3270 buffer into the program's dsect.
  • CASXB0053I Field out of sequence or overlaps another with MODE=OUT
    Runtime performance is improved when output fields are defined in sequence (ascending position), and do not overlap one another.
  • CASXB0054W Input performance is improved with fields in ascending sequence
    Runtime performance is improved when fields are defined in sequence (ascending position), though this is not required. However, arrays, groups and other dsect structures may prevent fields from being defined in pure ascending sequence.
  • CASXB0055W Field runs beyond end of defined map size.
    The field's position and length will cause it to extend beyond the defined (or implied) map dimensions. At runtime, if the map size equals the screen size, the field will wrap round to the beginning of the map. If the map size is smaller than the screen size, the field will extend beyond the end of the map. This can cause unpredictable results rendering user input at runtime.
  • CASXB0056W Comment-card continued. Contents of next line ignored.
    A comment card contained a non-blank character in column 72, indicating it is to be continued. This is syntactically correct, but may indicate a typographical error, and can cause the next macro to be accidentally ignored.
  • CASXB0057E There was no preceding DFHMSD TYPE=MAP/DSECT
    End-of-file was reached without finding a valid mapset definition.
  • CASXB0058I TYPE=FINAL accepted, but is undocumented mainframe behavior
    The TYPE=FINAL parameter should be coded on a closing DFHMSD (mapset) macro. However, in some installations, it can be coded on a DFHMDI (map) macro, though this is not documented CICS behavior.
  • CASXB0059I Loading as an MF <product> type file
    The input file extension is causing the file to be read as a <product> (Forms, Forms2, Screens) file. This informational message can help clarify if a file does not appear to be loading properly.
Parent topic: CASXB Error Messages


CASXB0040S The input file is not a valid MF Forms .frm file

The input file has an .frm (upper or lowercase) extension, but is not a valid Micro Focus Forms file. Some compatibility exists for migrating Micro Focus Forms files into this screen painter's native format, though some incompatibility does exist.
System Action:
Loading of the input file is terminated.
Resolution:
If the file was created by a version of Micro Focus Forms, contact product support with the input file being used. Otherwise, rename the input file using an extension other than ".frm".
Module:
scrload
Destination:
stdout
Parent topic: CASXB0040 - CASXB0059


CASXB0041W No comma after last parm, continuation cards are comments

This card is continued, but the last parameter was not followed by a comma. Therefore, continued cards are a continuation of comment text.
System Action:
Continued cards treated as comments.
Resolution:
This is a warning only, to prevent an inadvertent omission of a trailing comma on lines you wish to continue. This is syntactically correct, however.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0042W Expected another parameter following the last comma

The last parameter on this card was followed by a comma, indicating that more parameters would follow. However, none were found.
System Action:
The remainder of the macro, if any, is discarded.
Resolution:
Check for an omitted continuation character, or an extraneous comma following the last parameter. Use a hex editor to check that the card does not have any nonprintable characters. If it does, these are often coded or interpreted inconsistently, using a hex-00 prefix for ASCII characters in the range x'00'-x'1f'. Consult your COBOL System Reference manual for a discussion of the +N runtime switch for details. If these characters appear in your source deck, you should replace them with hex notation.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0043S The input file is not a valid MF Screens .srn file

The input file has an .srn (upper or lowercase) extension, but is not a valid Micro Focus Screens file. Some compatibility exists for migrating Micro Focus Screens files into this screen painter's native format, though some incompatibility does exist.
System Action:
Loading of the input file is terminated.
Resolution:
If the file was created by a version of Micro Focus Screens, contact product support with the input file being used. Otherwise, rename the input file using an extension other than ".srn".
Module:
scrload
Destination:
stdout
Parent topic: CASXB0040 - CASXB0059


CASXB0044E Repeated fields must be vertically or horizontally adjacent

obsolete.
System Action:
n/a.
Resolution:
n/a.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0045E Repeated field/group is not symmetric/balanced

obsolete.
System Action:
n/a.
Resolution:
n/a.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0046I No DFHMDI SIZE arg. Using configured default map size

This map does not have an explicit SIZE parameter, which will cause it to be displayed differently on different display sizes. In order to render the map in the painter, the painter's default map size (configurable) is arbitrarily used. Note that any fields must be expressed as POS=offset instead of POS=(row,col). When regenerating BMS from the painter, if a map size is not specified, the generated field macros will be expressed as POS=nnnn instead of POS=(row,col).
System Action:
The painter renders the map using the configured default map size. If running in command line mode (dfhpbms), an arbitrary size of 60 rows by 140 cols is used for internal rendering only.
Resolution:
If the map size used by the painter does not render desired results, adjust the configured default map size, and reload the mapset. If you are running in command-line (dfhpbms) mode, you can ignore this message, unless it is followed by other messages related to fields being outside of the map bounds.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0047W POS=offset should be used when DFHMDI SIZE= is omitted

This map was defined without an explicit SIZE= argument, so specifying this field with POS=(row,col) may not be rendered as expected.
System Action:
The field is positioned using the specified POS=(row,col) and the configured default map size. When BMS is regenerated, the field will be generated with a POS=nnnn value.
Resolution:
Recommend changing the POS=(row,col) expression to a POS=nnnn expression, though this is not required.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0048W POS=(row,col) should be used when DFHMDI SIZE= is specified

This map was defined with an explicit SIZE= argument, so specifying this field with POS=nnnn is improper (though allowed).
System Action:
The field is positioned using the specified POS=nnnn and the specified map size. When BMS is regenerated, the field will be generated with a POS=(row,col) value.
Resolution:
Recommend changing the POS=nnnn expression to a POS=(row,col) expression, though this is not required.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0049W CTRL ignored... Already specified in DFHMSD macro

The CTRL parameter was already specified in the DFHMSD macro. Contrary to the CICS 3.3 Applications Programming Reference Manual, and contrary to normal inheritance rules, this value does not supersede the mapset specification.
System Action:
The map's CTRL parameter is ignored.
Resolution:
Remove one or the other CTRL parameter.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0050W ATTRB=IC specified for a protected field. Accepted.

A protected field (ASKIP or PROT) wouldn't normally have the cursor placed in it, though it is allowed, since the application may dynamically change the field to unprotected before the map is sent.
System Action:
Accepted as written.
Resolution:
If not intended, consider correcting this apparent conflict.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0051E Repeated fields must have same LENGTH, PICIN and PICOUT

Repeated field (array) instances must yield compatible dsect definitions in order to be rendered into an array. Although some properties can differ, the LENGTH, PICIN and PICOUT values must be identical. The repeated field instance was detected by finding that the previous named field had the same alternate-name in its comment (SDF-mode or ADVS-mode only).
System Action:
The incompatible values are overridden by the preceding field's values.
Resolution:
Adjust the incompatible values to match. If this is not supposed to be a repeated field instance, change the alternate-name (in the comment card) of one or the other.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0052W Field overlaps another with MODE=IN/INOUT

Overlapping input fields can cause ambiguity at runtime when rendering user input from the 3270 buffer into the program's dsect.
System Action:
In command-line mode (dfhpbms), the fields are accepted as written. In painter-mode (advscrns), the second field may not be regenerated properly.
Resolution:
Correct the BMS so that the fields do not overlap.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0053I Field out of sequence or overlaps another with MODE=OUT

Runtime performance is improved when output fields are defined in sequence (ascending position), and do not overlap one another.
System Action:
In command-line mode (dfhpbms), the fields are accepted as written. In painter-mode (advscrns), the second field may not be regenerated properly.
Resolution:
Correct the BMS so that the fields do not overlap.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0054W Input performance is improved with fields in ascending sequence

Runtime performance is improved when fields are defined in sequence (ascending position), though this is not required. However, arrays, groups and other dsect structures may prevent fields from being defined in pure ascending sequence.
System Action:
None.
Resolution:
Consider reordering the fields into ascending sequence, if possible.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0055W Field runs beyond end of defined map size.

The field's position and length will cause it to extend beyond the defined (or implied) map dimensions. At runtime, if the map size equals the screen size, the field will wrap round to the beginning of the map. If the map size is smaller than the screen size, the field will extend beyond the end of the map. This can cause unpredictable results rendering user input at runtime.
Resolution:
Consider moving or splitting the field such that it does not wrap the end of the map.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0056W Comment-card continued. Contents of next line ignored.

A comment card contained a non-blank character in column 72, indicating it is to be continued. This is syntactically correct, but may indicate a typographical error, and can cause the next macro to be accidentally ignored.
System Action:
The contents of the next card will be treated as comments.
Resolution:
Verify that you have not inadvertently asked that this comment card be continued onto the next line.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0057E There was no preceding DFHMSD TYPE=MAP/DSECT

End-of-file was reached without finding a valid mapset definition.
Resolution:
Verify that you have not inadvertently omitted a DFHMSD (mapset) and/or DFHMDI (map) macro.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0058I TYPE=FINAL accepted, but is undocumented mainframe behavior

The TYPE=FINAL parameter should be coded on a closing DFHMSD (mapset) macro. However, in some installations, it can be coded on a DFHMDI (map) macro, though this is not documented CICS behavior.
System Action:
Accepted as written. Processing of the input file is terminated.
Resolution:
Verify that this is not a typographical error.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0059I Loading as an MF <product> type file

The input file extension is causing the file to be read as a <product> (Forms, Forms2, Screens) file. This informational message can help clarify if a file does not appear to be loading properly.
System Action:
The file is read using the indicated %1$s file format.
Resolution:
If <product> is correct, ignore the message. If incorrect, rename the input file using a different file extension.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0040 - CASXB0059


CASXB0060 - CASXB0076

  • CASXB0060I Found a pattern of duplicate names; repeating as a group
    In SDF-mode, if the parser encounters a repeated pattern of alternate-names (comment-card names), it will attempt to render them into an instance of a repeated group definition. IBM SDFII allows users to specify group definitions on a DEFINE STRUCTURE panel, such that they are not fully enumerated in the resulting BMS. Therefore, the BMS parser will make a best-effort to render these into a group, so that an appropriate copybook can be generated. This is not fail-safe, however, and the preferred method is to ensure that group member fields are prefixed with a comment of the form * groupname(grp-occ).fieldname.
  • CASXB0061E <literal-string> literal contains unbalanced or extraneous quotes
    The value <literal-string> does not have a closing quote, or contains one or more extraneous quotes. This does not include the specification of a pair of quotes ('') to represent a single quote within a quoted string.
  • CASXB0062W Ignoring invalid ATTRB value "<attrb-value>"
    <attrb-value> is not a valid ATTRB value.
  • CASXB0063E A valid POS operand is required for a DFHMDF macro
    The field definition did not have a valid POS (position) specified, so cannot be rendered properly.
  • CASXB0064E ADVS field repeated in 3 dimensions. Collapsing into 2.
    An SDF-type repeated field definition, within a repeated group definition (defined or implied), contains a BMS OCCURS clause. This would logically yield a three-dimension array in a generated copybook. However, it cannot be internally represented by this product.
  • CASXB0065W Painter cannot regen ADVS 2-dim arrays. Generate using SDF mode.
    The BMS is processing in ADVS-mode, and contains a comment of the form "* fieldname(horiz-occ)(vert-occ)" or "* fieldname(vert-occ)" and an OCCURS= clause. These are migrated internally as a repeating field within a repeating group for backward compatibility. However, ADVS-mode comments do not support group definition, so the BMS should be regenerated in SDF-mode.
  • CASXB0066W Name "<label>" exceeds 30 characters - truncated
    Names (labels) for fields (and compound fields) cannot exceed 30 characters. This limit may be 7 characters for some older host assemblers.
  • CASXB0067W Duplicate BMS label <old-name>
    Names (labels) used for the mapset, maps, fields and GRPNAME (compound-fields) must be unique within a mapset.
  • CASXB0068E PICIN/PICOUT can only be specified when LANG=COBOL or PLI
    PICIN and PICOUT specifications are only allowed for COBOL and PL/I installations.
  • CASXB0069E PICIN cannot be specified with MODE=OUT
    A PICIN specification is not valid for an output-only map.
  • CASXB0070E PICOUT cannot be specified with MODE=IN
    A PICOUT specification is not valid for an input-only map.
  • CASXB0071E PICIN is illegal at character <pic-pos>
    The PICIN value is not a valid input picture clause for the selected language. For COBOL language, in addition to editing for a syntactically valid COBOL picture, the system checks that it contains only the editing symbols A P S V X 9 / G or N. For PL/I language, only a cursory syntax check is made for valid tokens and repeaters.
  • CASXB0072E PICOUT is illegal at character <pic-pos>
    The PICOUT value is not a valid output picture clause for the selected language. For COBOL language, in addition to editing for a syntactically valid COBOL picture, the system checks that it contains only the editing symbols A B E P S V X Z 0 9 , . + - * $ CR DB / G or N. For PL/I language, only a cursory syntax check is made for valid tokens and repeaters.
  • CASXB0073E PICIN/PICOUT string cannot exceed 32 characters
    Picture strings greater than 32 token-characters cannot be properly edited. In many installations, they are not valid picture expressions for the native language.
  • CASXB0074S ASCII/EBCDIC conversion error, rc=return-code
    A system error occurred while translating a string from ASCII to EBCDIC, or vice-versa.
  • CASXB0075W Option option-name is not supported by the emulator
    option-name was found in the source deck, but will not be supported by CICS emulation.
  • CASXB0076E parameter value cannot exceed max-size character(s)
    Parameter parameter was found to contain a value that exceeded max-size.
Parent topic: CASXB Error Messages


CASXB0060I Found a pattern of duplicate names; repeating as a group

In SDF-mode, if the parser encounters a repeated pattern of alternate-names (comment-card names), it will attempt to render them into an instance of a repeated group definition. IBM SDFII allows users to specify group definitions on a DEFINE STRUCTURE panel, such that they are not fully enumerated in the resulting BMS. Therefore, the BMS parser will make a best-effort to render these into a group, so that an appropriate copybook can be generated. This is not fail-safe, however, and the preferred method is to ensure that group member fields are prefixed with a comment of the form * groupname(grp-occ).fieldname.
System Action:
The system attempts to render the repeated pattern of fields into a repeated group instance.
Resolution:
Consider explicitly defining the group members with comments of the form * groupname(grpocc).fieldname.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0061E <literal-string> literal contains unbalanced or extraneous quotes

The value <literal-string> does not have a closing quote, or contains one or more extraneous quotes. This does not include the specification of a pair of quotes ('') to represent a single quote within a quoted string.
System Action:
The quoted value is truncated.
Resolution:
Examine the <literal-string> for typographical errors and balanced quotes.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0062W Ignoring invalid ATTRB value "<attrb-value>"

<attrb-value> is not a valid ATTRB value.
System Action:
The value is discarded. Other ATTRB values specified, if any, are retained.
Resolution:
Check the spelling of <attrb-value>.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0063E A valid POS operand is required for a DFHMDF macro

The field definition did not have a valid POS (position) specified, so cannot be rendered properly.
System Action:
The field is arbitrarily placed at POS=(1,1) so that processing can continue.
Resolution:
Specify a valid position for the field.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0064E ADVS field repeated in 3 dimensions. Collapsing into 2.

An SDF-type repeated field definition, within a repeated group definition (defined or implied), contains a BMS OCCURS clause. This would logically yield a three-dimension array in a generated copybook. However, it cannot be internally represented by this product.
System Action:
The outer two dimensions are collapsed into one. This will render a similar two-dimension array that covers the same area of memory.
Resolution:
Replace the BMS OCCURS specification with multiple field macros that follow the SDF-type repeated field specification.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0065W Painter cannot regen ADVS 2-dim arrays. Generate using SDF mode.

The BMS is processing in ADVS-mode, and contains a comment of the form "* fieldname(horiz-occ)(vert-occ)" or "* fieldname(vert-occ)" and an OCCURS= clause. These are migrated internally as a repeating field within a repeating group for backward compatibility. However, ADVS-mode comments do not support group definition, so the BMS should be regenerated in SDF-mode.
System Action:
The two-dimension repeated field is internally migrated into a repeating field within a repeating group.
Resolution:
Switch to SDF-mode before regenerating the BMS.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0066W Name "<label>" exceeds 30 characters - truncated

Names (labels) for fields (and compound fields) cannot exceed 30 characters. This limit may be 7 characters for some older host assemblers.
System Action:
The name is truncated at 30 characters.
Resolution:
Specify a shorter <label> for the field.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0067W Duplicate BMS label <old-name>

Names (labels) used for the mapset, maps, fields and GRPNAME (compound-fields) must be unique within a mapset.
System Action:
The name is accepted as presented.
Resolution:
Change the name to a value unique within this mapset definition.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0068E PICIN/PICOUT can only be specified when LANG=COBOL or PLI

PICIN and PICOUT specifications are only allowed for COBOL and PL/I installations.
System Action:
Discard the picture specification.
Resolution:
Change the mapset LANG specification, or remove the PICIN/PICOUT parameters.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0069E PICIN cannot be specified with MODE=OUT

A PICIN specification is not valid for an output-only map.
System Action:
Discard the PICIN specification.
Resolution:
Remove the PICIN specification, or change the map's MODE to allow input.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0070E PICOUT cannot be specified with MODE=IN

A PICOUT specification is not valid for an input-only map.
System Action:
Discard the PICOUT specification.
Resolution:
Remove the PICOUT specification, or change the map's MODE to allow output.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0071E PICIN is illegal at character <pic-pos>

The PICIN value is not a valid input picture clause for the selected language. For COBOL language, in addition to editing for a syntactically valid COBOL picture, the system checks that it contains only the editing symbols A P S V X 9 / G or N. For PL/I language, only a cursory syntax check is made for valid tokens and repeaters.
System Action:
Discard the PICIN specification.
Resolution:
Correct the PICIN specification.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0072E PICOUT is illegal at character <pic-pos>

The PICOUT value is not a valid output picture clause for the selected language. For COBOL language, in addition to editing for a syntactically valid COBOL picture, the system checks that it contains only the editing symbols A B E P S V X Z 0 9 , . + - * $ CR DB / G or N. For PL/I language, only a cursory syntax check is made for valid tokens and repeaters.
System Action:
Discard the PICOUT specification.
Resolution:
Correct the PICOUT specification.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0073E PICIN/PICOUT string cannot exceed 32 characters

Picture strings greater than 32 token-characters cannot be properly edited. In many installations, they are not valid picture expressions for the native language.
System Action:
Discard the picture specification.
Resolution:
Shorten the picture clause by using repeaters (e.g., x(3) instead of xxx).
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0074S ASCII/EBCDIC conversion error, rc=return-code

A system error occurred while translating a string from ASCII to EBCDIC, or vice-versa.
System Action:
The string is discarded.
Resolution:
Report the problem to Micro Focus.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0075W Option option-name is not supported by the emulator

option-name was found in the source deck, but will not be supported by CICS emulation.
System Action:
The option is checked for syntax, but will be ignored at run-time.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXB0076E parameter value cannot exceed max-size character(s)

Parameter parameter was found to contain a value that exceeded max-size.
System Action:
The value is rejected.
Resolution:
Adjust the value accordingly.
Module:
scrload
Destination:
.TRL file
Parent topic: CASXB0060 - CASXB0076


CASXO Error Messages

  • CASXO0001 - CASXO0015
  • CASXO0016 - CASXO0029
Parent topic: Enterprise Server Error Messages


CASXO0001 - CASXO0015

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

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

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.

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.

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

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.

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.

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.

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.

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.
System Action:
None
Resolution:
None
Destination:
console
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0016 - CASXO0029

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

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

This contains the available user exits:

  • Exit Points
  • Support Functions
  • Structures
Parent topic: Enterprise Server Reference


Exit Points

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.
  • Configuring Whether a Message Shows in the Console
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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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


Configuring Whether a Message Shows in the Console

The user exit casmguex controls whether a particular message is output to the console or not.

To enable the user exit, it must be in a directory included on the appropriate program search concatenation. casmguex is then invoked by the SEP before sending the processed message to the console daemon.

The entry point of casmguex is a single parameter defined as a group item:

           03 MsgRB-Buffer.
              05 MsgRB-Buffer-Length   pic x(2) comp-x value 256.
              05 MsgRB-Buffer-Text.
                 07 MsgRB-Buffer-Char pic x
                    occurs 256 times depending on MsgRB-Buffer-Length.

The user exit examines the message and then determines whether to display it in the console or not. This is controlled through the use of return-code using the following values:

1
Display message
0
Do not show message

Example

The following sample program shows how you can use casmguex to prevent the error message FC0009I from showing:

       identification division.
       program-id. casmguex.
       environment division.
       configuration section.
       data division.
       working-storage section.
       local-storage section.
       linkage section.
       01  MsgRB-Buffer.
           03  MsgRB-Buffer-Length     pic x(2) comp-x.
           03  MsgRB-Buffer-Text.
               05  MsgRB-Buffer-Char   pic x
                occurs 256 times depending on MsgRB-Buffer-Length.
       procedure division using MsgRB-Buffer.
           move 1                      to return-code
           if MsgRB-Buffer-Text(4:7) = 'FC0009I'
           move 0                  to return-code
           end-if

           goback.

       end program casmguex.
Parent topic: Exit Points


Support Functions

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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


MQ Listener and Writer Types

Unknown (Unkn)
The listener or writer type assigned before the first message is received.
Trigger Monitor (Trig)
User-defined listener for an MQ initiation queue.
IMS-Bridge (I-Br)
An MQ-IMS Bridge listener or writer.
Parent topic: Enterprise Server Reference


Reference for MSS Deployment

  • CICS Commands
  • Data Conversion
  • CICS Resource Definitions
  • CICS Supplied Transactions
  • IMS Support in Enterprise Server
  • JCL Commands
  • JCL Environment Variables
  • TSO Support in Enterprise Server
    Describes use of TSO commands in Enterprise Server using the ISAEDT01 utility.
  • MSS Error Messages
Parent topic: Enterprise Server
Parent topic: Mainframe Support for Deployed Applications


CICS Commands

  • caspcrd
    Creates resource definition and conversion table files, and populates them with default entries.
  • cascnvim
    Imports a file containing mainframe data conversion macros into the file dfhdrcnv.dat.
  • casfile
    Changes the information held about a file.
  • casrdtex
    Exports CICS resources to a Resource Definition Table (.rdt) file.
  • casrdtup
    Imports CICS resources from a resource definition table (.rdt file).
  • caspcupg
    Updates a resource definition file.
  • castran
    Retrieves or updates information on CICS transactions or batch programs (limited functions). Its primary use is to enable and disable transactions, but it can be used to alter other values such as the TWA size or timeout values, and to display the status of transactions. It can also perform a PHASEIN or NEWCOPY on CICS programs that are defined in the PPT.
Parent topic: Reference for MSS Deployment


caspcrd

Creates resource definition and conversion table files, and populates them with default entries.

Syntax:

caspcrd [/res-name][/c][/cc][/cb][/dp=resource-definition-path][/o]

Parameters:

/res-name | Name of the enterprise server. Defaults to ESDEMO
/c | Create a resource definition file
/cc | Create a conversion table file
/cb | Create a resource definition file and a table conversion file
/dp=resource-definition-path | The resource-definition-path specifies the path within which the files are created. Defaults to the current directory
/o | Overwrite existing files

Dependencies:

You must have started the enterprise server before you can issue a caspcrd command.

Comments:

On UNIX you can use a dash (-) instead of a forward slash (/).

If a path or filename contains spaces, it should be enclosed in quotation marks. For example, "e:\dev mto\files".

Parent topic: CICS Commands


cascnvim

Imports a file containing mainframe data conversion macros into the file dfhdrcnv.dat.

Syntax:

cascnvim /f{file-name}] [/op{path}] [/q] [/o]

Parameters:

/f{file-name} | Path and filename of the data conversion macros file
/op{path} | Path to the directory in which dfhdrcnv.dat is created
/q | Run in quiet mode; that is, the contents of the data conversion macros file are not displayed
/o | Overwrite existing entries

Dependencies:

The /op parameter sets the environment variable TXRDTP, which determines where dfhdrcnv.dat is created.

Comments:

If /op{path} or TXRDTP is not set, dfhdrcnv.dat is created in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\cas .

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

If a path or filename contains spaces, it should be enclosed in quotation marks. For example, "e:\dev mto\files" .

Parent topic: CICS Commands


casfile

The casfile command enables you to change the information held about a file.

Syntax:

casfile {/rserver-name | /mserver-name | /fserver-name} [/dfile-DD-name]
[/e{e|u|d}][/iinput-script][/loutput-log]
[/o{oi|c}][/pnew-dataset-path][/s{y|n|a}][/t{y|n}][/w{w|r}][/uuserid][/apassword][/cgroup]
[/y]

Parameters:

/rserver-name
Name of the enterprise server to connect to. Defaults to ESDEMO
Note: When calling this utility from JCL or 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 /m or /f options to connect to the server.
or:
/mserver-name
Location of the Web Services and J2EE listener for the enterprise server you want to connect to. Where server-name takes the form prototype:host:WebServicePort. For example, /mtcp:localhost:9003
or:
/fserver-name
Name of the enterprise server to connect to. This differs from the /r option, in that it performs a lookup to locate the Web Service for the enterprise server. Where server-name takes the form prototype:host:port using MFCC.
/dfile-DD-name
Name of the file whose information you want to change. This is the eight-byte DD name, identical to the one held in the FCT for the file.
/e{e|u|d}
Sets the file status, where:
e
Enable; default
u
Unenable
d
Disable
/iinput-script
Name of a file containing the parameters for the file named in file-DD-name or to multiple files.
/loutput-log
Name of file to contain the results of executing the command. The default is that the results are displayed on the enterprise server console.
/o{oi|c}
Sets the open status, where:
o
Important: -oo has been deprecated. When used, a return code 4 (warning) is received.

Instead of -oo, use the -ooi (open immediate) option. If -oo is used with a region configured for VSAM shareoption use, -ooi will be forced.

oi
Open immediate.
c
Closed.
/pnew-dataset-path
Name of a new path for the file.
/s{y|n|a}
Output full file status, where:
y
Display; default
n
Suppress
a
All files
/t{y|n}
Switch the file handler trace on or off for all files, where:
y
On; default
n
Off
/w{w|r}
Set write status, where:
w
Read/write; default
r
Read-only
/uuserid
The user ID authorizing the change.
/apassword
The password for the authorizing user ID.
/cgroup
The group to be used when running casfile commands.
If you are using external security with an enterprise server, by default, a user is assigned to their default group at logon. If the permissions in this group are not sufficient for the casfile operation, use this option to specify another group.
/y
For ES.NET CICS regions, this option attempts to ensure all FCT catalog entries defined as remote resources are current.
Note: Options /r, /m, /f are alternative ways of identifying the enterprise server that you want to connect to.

Dependencies:

You must have started the enterprise server before you can issue a casfile command.

Comments:

The /s and /f options are alternatives and are mutually exclusive.

On UNIX, you can use a dash (-) instead of a forward slash (/).

If a path or filename contains spaces, it should be enclosed in quotation marks. For example,"e:\dev server\files"

Parent topic: CICS Commands


casrdtex

Exports CICS resources to a Resource Definition Table (.rdt) file.

Syntax:

casrdtex /ofile-name [/a] [/e] [/ipresource-file-path] [/uuserid] [/ppassword] [/q] [/v]
 [/s[sit1[,sit2]...]] [/l[list1[list2]...]]
 [/n[snt1[,snt2]...]] [/g[grp1[,grp2]...]]
 [/m] [/x] [/f] [/t] [/y] [/d] [/j] [/i] [/z] [/c] [/b] [/ue:{exit-name}] [/ur] [/tc] [/ws] [/pl] [/dt] [/tl]

Parameters:

/ofile-name | The RDT file to export to. This parameter is mandatory.
/a | Append to an existing file
/e | Include non-IBM-compatible entries (Micro Focus extensions to the format, which all begin with an underscore)
/ipresource-file-path | The directory containing the CICS resource definition file, dfhdrdat, from which to export. This defaults to %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\cas .
/uuserid | User ID
/ppassword | Password
/q | Run in quiet mode
/v | Run in verbose mode
/s[sit1[,sit2]...] | Include the specified SITs in the export. If you specify just the switch, all are exported.
/l[list1[list2]...] | Include the specified startup lists (GRPLIST) in the export. If you specify just the switch, all are exported.
/n[snt1[,snt2]...] | Include the specified sign-on entries in the export. If you specify just the switch, all are exported.
/g[grp1[,grp2]...] | Include the specified groups in the export. If you specify just the switch, all are exported.

The remaining parameters select which table entries for the selected group(s) are to be included:

/m | Processing program table (PPT)
/x | Program control table (PCT)
/f | File control table (FCT)
/t | Terminal (TRM)
/y | Terminal type (TTY)
/d | TD queue (TDQ)
/i | Program list (PLT)
/j | Journal (JCT)
/z | Temporary storage (TST)
/c | Connection
/b | X/Open DB compatibility
/ue:{exit-name} | Name of user exit
/ur | URI map
/tc | TCPIP service
/ws | Web service
/pl | Pipeline
/dt | Doctemplate
/tl | Transaction class

Dependencies:

Run casrdtex from an Enterprise Developer command prompt to ensure that all of the necessary paths are available.

Comments:

If a path or filename contains spaces, it should be enclosed in quotation marks. For example, "e:\dev mto\files".

Example:

casrdtex /oresfile.rdt /ggroup1,group3 /m /x /ip"e:\dev mto\files"

The above command exports the PPT and PCT entries for the groups group1 and group3, from the dfhdrdat file in "e:\dev mto\files", to the file resfile.rdt.

casrdtex /oresfile.rdt /s /g /f /ip"e:\devmto\files"

The above command exports all SITs, and the FCT entries for all groups, to the file resfile.rdt.

Parent topic: CICS Commands


casrdtup

Imports CICS resources from a resource definition table (.rdt file).

Syntax:

casrdtup /ffile-name [/opresource-definition-path] [/rregion-name] [/uuserid]
[/ppassword] [/xext] [/q] [/o] [/d]

Parameters:

/ffile-name | The RDT file to import from. This parameter is mandatory.
/opresource-definition-path | The directory containing the resource definition file, dfhdrdat, into which resources are imported. This defaults to %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\cas .
/rregion-name | The name of the region into which the resources will be imported
/uuserid | User ID
/ppassword | Password
/xext | Default FCT file extension
/q | Quiet mode (no prompts)
/o | Overwrite existing entries. If this is not specified, any duplicate entry results in an error message.
/d | Discard MVS data set names

Dependencies:

To ensure that casrdtup is on your PATH, execute it from an Enterprise Developer command prompt.

Comments:

If a path or filename contains spaces, it should be enclosed in quotation marks. For example, "e:\dev mto\files".

This utility is designed to process mainframe generated resource definition records, which are not abbreviated. However, it will accept abbreviations for keywords and values, provided that the abbreviations are unique. For example, DSNA can be used in place of DSNAME, and BR can be used in place of BROWSE.

This utility expects values to be uppercase like those generated by the mainframe utility, DFHCSDUP. For example, "NONE" and "YES" rather than "None" and "Yes".

For more on the resource definitions that you can use with Enterprise Server MSS, see Resource Definitions.

Example:

casrdtup /fresfile.rdt /d /op"e:\devmto\files"

The above command imports the file resfile.rdt, discarding MVS data set names.

Parent topic: CICS Commands
Related information
Resource Definitions


caspcupg

Updates a resource definition file.

Syntax:

caspcupg [/res-name]
         [/dp=resource-defn-path]
         [/s(sit,fs-server-id)]
         [/f(group,fs-server-id)]
         [/o]
         [/uuserid]
         [/ppassword]
         [/sparameter]
         [/ssparameter]
         [/bpath]
         [/t=]
         [/td]
         [/z]
         [/x]

Parameters:

/res-name | Name of the enterprise server. Defaults to ESDEMO
/dp=resource-defn-path | Resource Definition Path.
/s(sit,fs-server-id) | Set FCT FSID in SIT and groups in startup list
or: |
/f(group, fs-server-id) | Set FCT FSID in group.
/o | Force upgrade of non-DFH-supplied resources.
/uuserid | User ID for updates
/ppassword | Password for updates
/sparameter | Set FCT start-open to parameter., which must be "Y" or "N"
/ssparameter | Set security on or off. parameter is + for on, or - for off
/bpath | Optional. Path to location to create backup file.
/t= | Set Termtype Device properties = Mapping properties
/td | Allow Termtype Device properties to differ from Mapping properties
/z | Reset blank PCT security keys to default value
/x | Quiet mode

Dependencies:

You must have started the enterprise server before you can issue a cascugp command.

Comments:

The /s and /f options are alternatives and are mutually exclusive.

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

If a path or filename contains spaces, it should be enclosed in quotation marks. For example, "e:\dev mto\files".

Parent topic: CICS Commands
Related concepts
Defining IMS Resources


castran

Retrieves or updates information on CICS transactions or batch programs (limited functions). Its primary use is to enable and disable transactions, but it can be used to alter other values such as the TWA size or timeout values, and to display the status of transactions. It can also perform a PHASEIN or NEWCOPY on CICS programs that are defined in the PPT.

The NEWCOPY option loads a new copy of the specified program only if it is not currently in use; otherwise, it will fail. The PHASEIN option loads a new copy even if the program is currently running. Where this is the case, the previously loaded copy remains until it is no longer in use. All requests that occur after the reload use the new copy.

Note: castran can also be invoked from within a JCL by writing a simple COBOL program to call it.

Syntax:

castran [/res-name] [/mprototype:host:WebServiceport] [/fserver-name]
    [/ttrans-id]
    [/e{e|d}]
    [/s{y|n|a}]
    [/g{y|n}]
    [/j{d|a}]
    [/d{y|n}]
    [/loutput-log]
    [/wTWA-size]
    [/qinput-timeout]
    [/xrunaway-timeout]
    [/ydeadlock-timeout]
    [/pprogram-name]
    [/nprogram-name]
    [/vbatch-program-name]
    [/uuserid]
    [/apassword]
    [/cgroup]

Syntax to issue multiple commands from a command file:

castran [/res-name] [/mprototype:host:WebServiceport] [/fserver-name] /iinput-script-file

Parameters:

/res-name
Name of the enterprise server to connect to. Defaults to ESDEMO.
Note: When calling this utility from JCL or 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 /m or /f options to connect to the server.
or:
/mprototype:host:WebServiceport
Location of the Web Services and J2EE listener for the enterprise server you want to connect to. For example, /mtcp:localhost:9003
or:
/fserver-name
Name of the enterprise server to connect to. This differs from the /r option, in that it performs a lookup to locate the Web Service for the enterprise server.
[-iinput-script-file]
The input script file which will contain a list of commands to run. Any comment line in the scriptfile must have # in column 1.
[-ttrans-id]
Four byte transaction ID.
[-e{e|d}]
Set the Enable status for the specified transaction:
Setting | Description
e or no value | Enable
d | Disable
[-s{y|n|a}]
Output the full transaction status for the specified transaction.
Setting | Description
y or no value | Display
n | Suppress
a | Display details for all transactions in PCT irrespective of the transaction id specified using the /t option
[-g{y|n}]
Set the Upper Case Translation status for the specified transaction.
Setting | Description
y or no value | UC Translation
n | No UC Translation
[-j{d|a}]
Set the Screen status for the specified transaction.
Setting | Description
d or no value | Default
a | Alternate
[-d{y|n}]
Set the Transaction Dump status of the specified transaction.
Setting | Description
y | Transaction Dump
n or no value | No Transaction Dump
[-loutput-log]
The file to which the output from the command is written. The default is to standard output.
[-wTWA-size]
Set the TWA Size {0..32767} for the specified transaction.
[-qinput-timeout]
Set the Input Timeout for the specified transaction.
Setting | Description
s or no value | System default
0..408000 | Timeout value in hundredths of a second
[-xrunaway-timeout]
Set the Runaway Timeout for the specified transaction.
Setting | Description
s or no value | System default
100..270000 | Timeout value in hundredths of a second
[-ydeadlock-timeout]
Set the Deadlock Timeout for the specified transaction.
Setting | Description
s or no value | System default
0..408000 | Timeout value in hundredths of a second
[-pprogram-name]
Issue a PHASEIN for the specified program. Please note: this is unrelated to any transaction id specified with the /t option.
[-nprogram-name]
Issue a NEWCOPY for the specified program. Please note: this is unrelated to any transaction id specified with the /t option.
[-vbatch-program-name]
Issue a NEWCOPY for the specified non-CICS program. Please note: this is similar to issuing a CNCL for a CICS program, in that the latest copy will be loaded upon the next invocation.
[-uuserid]
Authorization User ID
[-apassword]
Authorization Password
[-cgroup]
Authorization Group (Optional)
Note: Options /r, /m, /f are alternative ways of identifying the enterprise server that you want to connect to.

Return Codes:

0 | Success
4 | Invalid flag/Duplicate flag(s)
12 | Transaction ID not found in PCT/Program not found in PPT/Incorrect user ID or password
15 | Region not running/invalid command

Dependencies:

You must have started the enterprise server before you can issue a castran command.

Comments:

Multiple usage of the same parameter type, results in only the first occurrence being use. All others will be ignored.

Exceeding the maximum value for TWA size or any of the timeout options, will result in the maximum value being set.

You can use a dash (-) instead of a forward slash (/) to indicate command options.

Script files must contain a transaction ID or program name on each line (except for comments), but cannot contain region names; that is, all commands in a file relate to one region, which is specified in the initial castran call. If a path or filename contains spaces, it should be enclosed in quotation marks. For example:

castran /rESDEMO /i"c:\input scripts\my script.txt"

In order to use castran with an Enterprise Server that has security enabled, you must ensure that all resource definitions are up to date. You can do this by issuing the following command:

caspcupg /r<server name> /dp=<dfhdrdat path>

Examples:

To disable a CICS transaction called ACCT and display its status on a region called ESDEMO:

castran /rESDEMO /tACCT /ed /sy

To alter the TWA size and turn off UC Translation for ACCT in a secure region:

castran /rESDEMO /uSYSAD /aSYSAD /w255 /gn /tACCT

To perform multiple operations by using an input script:

castran /rESDEMO /imultiple_cmds.txt

Where multiple_cmds.txt contains the following lines:

# multiple castran commands
/tACCT /ed
/tAC01 /ee /ja
/nACCT00
Parent topic: CICS Commands


Data Conversion

The following features of IBM's DFHCNV macros are supported:

Keyword | Support
DFHCNV TYPE=INITIAL |
CLINTCP=nnnn | Recognized
SRVERCP=nnnn | Recognized
CDEPAGE=nnnn | Recognized
DFHCNV TYPE=ENTRY |
RTYPE={FC|TS|TD|IC|PC} | Full
CLINTCP=nnnn | Recognized
SRVERCP=nnnn | Recognized
RNAME=resourcename | Full
XRNAME=xxxxxxxxxxxxxxxx | Full
USREXIT={YES|NO} | Recognized
CDEPAGE=nnnn | Recognized
DFHCNV TYPE=KEY |
TYPE=SELECT | Full
OPTION={COMPARE|DEFAULT} | Full
OFFSET=nnnn | Full
DATA='dd...dd' | Full
XDATA='xx...xx' | Full
DFHCNV TYPE=FIELD |
OFFSET=nnnn | Full
DATATYP={CHARACTER|PD|BINARY |NUMERIC} | Full
DATATYP={USERDATA|GRAPHIC} | Recognized
USRTYPE=xx | Recognized
DATALEN=n | Full
LAST=YES | Full
SOSI=YES|NO | Recognized
DFHCNV TYPE=FINAL | Full
DFHCNV TYPE={DSECT|IVP} | Recognized

The following terms are used to describe the level of support provided for keywords:

  • Full - Fully supports the function or operand
  • Recognized - Recognizes the function or operand but takes no action on it at run time
Parent topic: Reference for MSS Deployment


CICS Resource Definitions

In Mainframe Subsytem Support you can define a subset of the resource types that you can define in mainframe CICS. You can use the same definition mechanism as mainframe CICS: DEFINE statements followed by keywords that specify various attributes of the resource. The keywords differ depending on the resource being defined. DEFINE statements are held in resource definition table (.rdt) files, which constitute a staging post in the process of exchanging resource definitions with the mainframe CICS System Definition (CSD) file.

In mainframe CICS you can define many more types of resource than you can in Mainframe Subsytem Support, for example LSRPOOL and SESSIONS. Mainframe Subsytem Support does not support these resource types because they are meaningless on the target environment.

Mainframe Subsytem Support provides Micro Focus extensions for some resource types. These are extra keywords that define attributes specific to Mainframe Subsytem Support on the target environment.

In the following specifications of the resource type definitions, each keyword and its parameters is shown in a mixture of upper case and lower case. You need to specify at least the letters in upper case. For example, in the Connection definition, DE and DESCRIPTION are synonyms. However, we recommend that you specify keywords and parameters in full, as shown in the examples. Defaults are shown in bold.

Mainframe Subsytem Support also accepts DEFINE MAPSET and all its keywords, but it does not store these definitions as mapset definitions in the resource definition file. Instead it stores them as data tables (DEFINE PROGRAM with _MOduletype set to Data).

  • DEFINE CONNECTION
    Defines a remote system with which ES communicates via inter-region communication (IRC).
  • DEFINE FILE
    Defines the attributes and characteristics of a file used by Enterprise Server.
  • DEFINE PROGRAM
    Defines a program used to process transactions in Enterprise Server.
  • DEFINE TERMINAL
    Defines the characteristics of display devices and printers used by Enterprise Server.
  • DEFINE TRANCLASS
    Defines the attributes of a transaction class.
  • DEFINE TRANSACTION
    Defines the attributes of a transaction.
  • DEFINE TDQUEUE
    Defines the attributes of a transient data queue.
  • DEFINE TYPETERM
    Defines the attributes for a set of terminals that have similar characteristics.
  • DEFINE _SIGNON
    Defines user IDs and their level of access security to Enterprise Server resources.
  • DEFINE _JOURNAL
    Defines the attributes of a journal used for recording system activity within Enterprise Server.
  • DEFINE _PGMLIST
    Defines a list of programs and the phase in which they are to run. The lists are used at post initialization and shut down.
  • DEFINE _SIT
    Defines a system initialization table that controls the execution of an Enterprise Server region.
  • DEFINE _STARTUPLIST
    Defines a list of resource groups to be installed at system initialization.
  • DEFINE _TEMPSTORAGE
    Defines the attributes of a temporary storage (TS) record set.
  • DEFINE _XOPENCOMPAT
    Defines the attributes of XA compatible resources (external resource managers).
  • DEFINE JES
    Defines a JES/IMS initiator or a JES printer.
Parent topic: Reference for MSS Deployment
Parent topic: Resource Definitions


DEFINE CONNECTION

Defines a remote system with which ES communicates via inter-region communication (IRC).
Keyword | Description
Connection(name) | Specifies the logical name of this connection. Mandatory. Must be unique across all connected systems. Can be up to four alphanumeric characters.
Group(groupname) | Names the group the connection definition belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system groups.
Description(text) | Describes the connection. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
Connection Properties |
Netname(name) | Specifies the network name that identifies the APPLID of the remote system or region. name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Required in most circumstances.
PRotocol(Appc|Cci) | Identifies the connection method to be used for the connection: Appc: a remote connection over an LU6.2 link Cci: a remote connection through a CCI gateway Mandatory
Operational Properties |
INSERVICE(Yes|No) | Indicates whether or not this connection is in service; that is, whether transactions can be initiated and messages sent.
Security |
SEcurityname(name) | The security name of the remote system. Required only if the connection method is APPC. Can be up to eight alphanumeric characters from the set A through Z, 0 through 9, $, @ and #.
ATtachsec(Local|identify|Verify|Persistent|Mixedpe | The level of security required when a user attaches to this connection: Local: the authority of the user is taken to be that of the link Identify: Incoming attach requests must specify a user ID Verify: Incoming attach requests must specify both a user ID and a password Persistent: The first attach request must specify both a user ID and a password, but subsequent attach requests require only a user ID Mixedpe: Incoming attach requests may specify either Identify or Persistent
Micro Focus Extensions |
_OPERId(code) | Specifies an operator ID used for routing messages. Up to three alphanumeric characters. Optional.
_OPERPriority(number) | Specifies the operator priority for transactions initiated over this connection. Defaults to 0(zero). Operator priority is one factor in determining a transaction's execution priority, which is the sum of: Terminal priority Transaction priority Operator priority (this field) The sum cannot be greater than 255.
_Userid(name) | Specifies a user ID to be associated with the connection. Mandatory if no sign-on takes place on the connection.
_Natlang(E|K) | Specifies the national language in which messages are sent over the connection: E: English K: Kanji
_Sessionmax(number) | Specifies the maximum number of concurrent sessions for the connection. Defaults to 0(zero).
_Lualias(name) | Specifies the LU name by which the connection is known in the APPC configuration. Mandatory only where the connection method is APPC.
_Partneralias(name) | Specifies the name used by local transactions to refer to this partner LU. Mandatory only where the connection method is APPC.
_Aliasapplid(code) | Specifies the APPLID used by the APPC link. Mandatory only where the connection method is APPC.
_Modetable(name) | Specifies the name of the APPC transmission service profile that describes the APPC link between the local and partner LUs. Mandatory only where the connection method is APPC. It can be up to eight characters in length. The first character must be from the set A through Z and $. Subsequent characters can be from the set A through Z, 0 through 9 and $.
_CCIProtocol(CCITCPIP) | For connections where the connection method is CCI, specifies which CCI protocol is to be used: CCITCPIP: TCP/IP Mandatory.
_CCIMachine(name) | Names the machine on which on which the CCITCP2 daemon is running. Required only where CCIProtocol is CCITCPIP.
_MFNode(name) | Names the machine on which the target region runs. This is its IP name or IP address. _MFNode and _MFPort together equate to the socket used by the TCP/IP server for the remote target region that this connection definition describes. These fields are mandatory only where CCIProtocol is CCITCPIP and when using a direct connection to the remote region with no CCITCP2 daemon present on the network.
_MFport(number) | Identifies the port number for _MFNode. _MFNode and _MFPort together equate to the socket used by the TCP/IP server for the remote target region that this connection definition describes. These fields are mandatory only where CCIProtocol is CCITCPIP and when using a direct connection to the remote region with no CCITCP2 daemon present on the network..
  • Examples
Parent topic: CICS Resource Definitions


Examples

DEFINE CONNECTION(L001) GROUP(SAMPGRP)
DESCRIPTION(Sample APPC connection)
       NETNAME(NET081) INSERVICE(YES) SECURITYNAME(SESS1)
       ATTACHSEC(LOCAL) PROTOCOL(APPC)

DEFINE CONNECTION(C002) GROUP(SAMPGRP)
DESCRIPTION(Sample CCI connection)
       INSERVICE(YES) ATTACHSEC(LOCAL) PROTOCOL(CCI) _OPERPRTY(0)
       _NATLANG(E) _SESSIONMAX(0) _CCIPROTOCOL(CCITCP)
       _CCIMACHINE(cvimtb09)

DEFINE CONNECTION(L001) GROUP(SAMPGRP)
DESCRIPTION(Sample APPC connection with MF extensions)
       NETNAME(NET081) INSERVICE(YES) SECURITYNAME(SESS1)
       ATTACHSEC(LOCAL) PROTOCOL(APPC) _OPERPRTY(0) _USERID(U555)
       _NATLANG(E) _SESSIONMAX(4) _LUALIAS(MTB9AFG)
       _PARTNRALIAS(ASL8KKK) _ALIASAPPLID(MPAPP)
Parent topic: DEFINE CONNECTION
Related information
Resource Definitions


DEFINE FILE

Defines the attributes and characteristics of a file used by Enterprise Server.
Keyword | Description
File(name) | Names the file. Mandatory. name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #.
Group(groupname) | Names the group the file belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system groups.
Description(text) | Describes the file. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
VSAM
DSName(name) | Specifies the name of the physical file. This is a mainframe-style data set name of up to 44 characters.
Remote
REMOTESystem(name) Applicable only for remote files. Specifies the ID of the remote system that holds the file. This must correspond to either:
  • The Local SYSID field in the SIT used to run the related remote CICS region
  • The APPLID of another CICS system
REMOTEName(name) | Applicable only for remote files. Names the remote file. Necessary only if it differs from the local file name.
RECORDSize(number) | Applicable only for remote files. Specifies the maximum length in bytes of records in a remote file, in the range 1 through 32767.
Keylength(number) | Applicable only for remote files. Specifies the length in bytes of the key for a remote file, in the range 1 through 32767.
Initial Status
STAtus(Enabled|Disabled|Unenabled) Effective only for files owned by the local region. Specifies whether this file is accessible to transactions when the region is started.

Enabled: accessible at region startup

Disabled: not accessible at region startup

Unenabled: can be opened only by a SET FILE OPEN command. You cannot specify Unenabled for files of type Altindex

Opentime(Firstref|Startup) Indicates when the file is opened.

Firstref: the first time the file is referenced in the program being executed

Startup: when the region starts up

Note that this keyword controls only when the file is opened, not whether or not it is accessible; accessibility is controlled by the STAtus keyword.

Operations
Add(No|Yes) | Indicates whether users can add records to the file.
Browse(No|Yes) | Indicates whether users can browse the file.
DELete(No|Yes) | Indicates whether users can delete records from the file.
REAd(Yes|No | Indicates whether users can read records in the file.
Update(No|Yes) | Indicates whether users can update records in the file.
Recovery Parameters
RECOVery(None|Backoutonly|All) Specifies the recovery options for this file:

None: the file is not recoverable

Backoutonly; the file is a protected resource and changes can be backed out. You must also define the file as being held on a Fileshare server, as Fileshare is required for backward recovery.

All: the file is a protected resource and has both forward and backward recovery capability. For forward recovery journals are used to record changes to the file. You must also define the file as being held on a Fileshare server, as Fileshare is required for forward and backward recovery.

Security
RESsecnum(keys) | Specifies one or more indicators, each corresponding to one of the 24 resource keys for this file. A user has access to a particular resource only through a matching key as defined in his sign-on table entry. To toggle a key on you specify its number here. By default all keys are toggled off. You code the keys as a comma-separated list of individual numbers and ranges separated by hyphens. For example, to toggle the keys 1 to 5 and 10 on, code RESSECNUM(1-5,10).
Micro Focus Extensions
_MAxreclen(number) | Specifies the maximum logical record length of the file in bytes, in the range 1 through 32767. The value must be greater than or equal to the value of _Minreclen. Specify a value if _FILEType is one of the following: KSDS, RRDS, ESDS or the file is remote (you specified a value in Remotesystem(name)).
_MInreclen(number) | Specifies the minimum logical record length of the file in bytes , in the range 1 through 32767. The value must be less than or equal to the value of _Maxreclen. Specify a value if _FILEType is one of the following: KSDS, RRDS or ESDS.
_KEYPosition(number)

The key position is the offset, relative to zero, of the key from the beginning of the data record, in the range 0 through 32767. When set to 0, the key begins in the first position of the record. Specify a value if _FILEType is one of the following: KSDS or Altindex.

_KEYLength(number) Specifies the length of the record key in bytes, in the range 1 through 32767. The value of the following expression must not exceed the minimum record length:

key position + key length - 1

_FILEType(type) Specifies what type of file this is:

KSDS: key sequenced data set

ESDS; entry sequence data set

RRDS: relative record data set

Altindex: Alternate index for a KSDS file.

May be omitted if the file is defined as remote (you specified a value in Remotesystem(name)).

_Basefile(fileid) | For a file of type Altindex, specifies the base data file for which this is an alternate index. fileid must correspond to the file name of another file definition of type KSDS.
_Startempty(No|Yes) Indicates whether the current contents of the file are deleted when the region starts up:

No: the file contents are not deleted

Yes: the file contents are deleted

_Dupkey(No|Yes) | For an alternate index, indicates whether duplicate keys are allowed
_Path(string) | Specifies the path of the physical file if you want to override the default path. Do not include the filename or the file extension. Mandatory if the file is held on a Fileshare server, in which case _FILEShareid must be present too.
_FILEShareid(name) | Specifies the Fileshare server on which the file resides. name can be up to 16 characters in length.
_FILEFormat(Microfocus|IDXFMT4|IDXFMT8|IDXFMT9) | Specifies the format for files that are to be created by Mainframe Transaction Option. We recommend that you use the default, IDXFMT8.
_FILEName(name) | Specifies the name of the physical PC file if you want to override the default filename, which is the name given by File(name). Do not include the file extension.
_FILEExt(value) | Specifies the file extension of the physical file if you want to override the default, which is .dat
_Collseq(Ebcdic|Ascii) | Specifies the collating sequence used in the file.
  • Example
Parent topic: CICS Resource Definitions


Example

DEFINE FILE(SAMPLEA) GROUP(SAMPGRP)
DESCRIPTION(Sample KSDS FCT entry)
       STATUS(ENABLED) OPENTIME(STARTUP) RECORDFORMAT(F) ADD(YES)
       BROWSE(YES) DELETE(YES) READ(YES) UPDATE(YES)
       RECOVERY(BACKOUTONLY) _FILETYPE(KSDS) _MAXRECLEN(200)
       _MINRECLEN(200) _KEYPOSITION(1) _KEYLENGTH(6) _STARTEMPTY(YES)
       _DUPKEY(NO) _FILEEXT(DAT) _FILEFORMAT(MICROFOCUS)
DEFINE FILE(SAMPLEA1) GROUP(SAMPGRP)
DESCRIPTION(Index for SAMPLEA)
       STATUS(ENABLED) OPENTIME(FIRSTREF) RECORDFORMAT(F) ADD(YES)
       BROWSE(YES) DELETE(YES) READ(YES) UPDATE(YES)
       RECOVERY(BACKOUTONLY) _FILETYPE(ALTINDEX) _BASEFILE(SAMPLEA)
       _KEYPOSITION(8) _KEYLENGTH(4) _STARTEMPTY(NO) _DUPKEY(NO)
       _FILEEXT(DAT) _FILEFORMAT(MICROFOCUS)
DEFINE FILE(SAMPLEB) GROUP(SAMPGRP)
DESCRIPTION(Sample RRDS entry)
       STATUS(ENABLED) OPENTIME(FIRSTREF) RECORDFORMAT(F) ADD(YES)
       BROWSE(YES) DELETE(YES) READ(YES) UPDATE(YES)
       RECOVERY(BACKOUTONLY) _FILETYPE(RRDS) _MAXRECLEN(500)
       _MINRECLEN(500) _STARTEMPTY(NO) _DUPKEY(NO) _PATH(x:\cics\fshr)
       _FILESHAREID(FSHRCIC2) _FILEEXT(DAT) _FILEFORMAT(MICROFOCUS)
       RESSECNUM(01-08,17-22,24)
DEFINE FILE(SAMPLEC) GROUP(SAMPGRP)
DESCRIPTION(Example of an ESDS)
       STATUS(ENABLED) OPENTIME(FIRSTREF) RECORDFORMAT(F) ADD(YES)
       BROWSE(YES) DELETE(NO) READ(YES) UPDATE(NO)
       RECOVERY(BACKOUTONLY) _FILETYPE(ESDS) _MAXRECLEN(1000)
       _MINRECLEN(120) _STARTEMPTY(NO) _DUPKEY(NO) _FILEEXT(DAT)
       _FILEFORMAT(MICROFOCUS) _FILENAME(TESTC) _USECATALOG(NO)
Parent topic: DEFINE FILE


DEFINE PROGRAM

Defines a program used to process transactions in Enterprise Server.
Keyword | Description
PROGram(name) | Names the program. Mandatory. name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a program name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system programs.
Group(groupname) | Names the group the program belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as MSS uses that prefix for system groups.
DEscription(text) | Describes the program. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
Language(Cobol|Assembler|Pli) | Specifies the programming language that the program is written in.
RESident(No|Yes) Specifies whether the program is permanently resident in memory:

No: The program is removed from memory when the tasks using it have completed

Yes: The program remains in memory throughout the session

Status(Enabled|Disabled) Specifies whether the program is accessible when the region starts up:

Enabled: the program is accessible when the region starts up.

Disabled: The program cannot be used until it is specifically enabled using the transaction CPMT.

RSl(keys) | (RSl stands for Resource Security Level.) Specifies one or more indicators, each corresponding to one of the 24 resource keys for this program. A user has access to a particular resource only through a matching key as defined in his sign-on table entry. To toggle a key on you specify its number here. By default all keys are toggled off. You code the keys as a comma-separated list of individual numbers and ranges separated by hyphens. For example, to toggle the keys 1 to 5 and 10 on, code RSl(1-5,10).
Remote Attributes
REMOTESystem(name) Applicable only for remote programs. Specifies the ID of the remote system that holds the file. This must correspond to either:
  • The Local SYSID field in the SIT used to run the related remote CICS region
  • The APPLID of another CICS system
REMOTEName(name) | Applicable only for remote programs. Names the remote file. Necessary only if it differs from the local program name.
Transid(name) | Applicable only for remote programs. Specifies the name of the transaction that the remote system is to attach and under which it is to run the remote program. If not specified, the remote system executes the program under one of the supplied mirror transactions CSMI and CVMI. If supplied, name must be up to four characters in length
Micro Focus Extensions
_MOduletype(Program|Data) Specifies whether the resource being defined is an executable program or a data table:

Program: Resource is an executable program

Data: Resource is a data table. It can be loaded via an EXEC CICS LOAD PROGRAM command. Any attempt to use EXEC PROGRAM LINK or EXEC PROGRAM XCTL will fail with a PGMIDERR condition

_Wssavestate(No|Yes) | Specifies whether or not a program's working storage should be saved in its initial state so that it can be restored if the same program is called again at a lower level
_MAxcommarea(size) | Specifies the amount of storage to be allocated to the communications area (COMMAREA) to allow CICS to behave like mainframe CICS. The size is in the range 0 through 32767. The effect of this is that when a program is passed a COMMAREA smaller than the COMMAREA defined in the program, the passed COMMAREA is automatically extended in length to fill the defined space. This overrides the COMMAREA override value held in the SIT.
  • Example
Parent topic: CICS Resource Definitions


Example

DEFINE PROGRAM(TEST001) GROUP(TESTGRP)
LANGUAGE(COBOL) RESIDENT(NO) STATUS(ENABLED)
RSL(01,03,06,08-14,16,19-21)
DEFINE PROGRAM(TEST002) GROUP(TESTGRP)
DESCRIPTION(Sample PPT program)
LANGUAGE(ASSEMBLER) RESIDENT(NO) STATUS(DISABLED)
DEFINE PROGRAM(SAMP001) GROUP(SAMPGRP)
DESCRIPTION(Sample PPT with MF extensions)
LANGUAGE(COBOL) RESIDENT(NO) STATUS(ENABLED)
_MODULETYPE(PROGRAM) _WSSAVESTATE(NO) _MAXCOMMAREA(0)
DEFINE PROGRAM(DATA001) GROUP(SAMPGRP)
DESCRIPTION(Sample PPT for data table)
LANGUAGE(ASSEMBLER) RESIDENT(NO) STATUS(ENABLED)
_MODULETYPE(DATA) _WSSAVESTATE(NO) _MAXCOMMAREA(0)
Parent topic: DEFINE PROGRAM
Related information
Resource Definitions


DEFINE TERMINAL

Defines the characteristics of display devices and printers used by Enterprise Server.
Keyword | Description
TErminal(name) | Specifies the logical name of this terminal. Mandatory. Must be unique across all connected systems. Up to four alphanumeric characters.
Group(groupname) | Names the group the terminal definition belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system groups.
Description(text) | Describes the terminal. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
AUTINSTModel(No|Yes|Only) Specifies whether or not this terminal definition can be used as a model terminal definition for autoinstall:

Yes: can be used as a model for autoinstall, as well as for a specific device that is not autoinstalled

No: can be used only for a specific device that is not autoinstalled

Only: can be used only as a model for autoinstall

AUTINSTName(name) | Applicable only if AUTINSTModel is Yes or Only. Specifies the name by which the definition is known to the Autoinstall Control Program. name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Defaults to the value given by Terminal(name).
Terminal Identifiers
Typeterm(name) | Names the associated Typerterm definition, which must exist. Mandatory.
Netname(name) | Identifies the terminal to the network. Mandatory if AUTOINSTModel is Yes or No. name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. The first character must be a letter.
REMOTESYSTem(name) Applicable only for remote terminals. Specifies the ID of the remote system that holds the terminal definition. This must correspond to either:
  • The Local SYSID field in the SIT used to run the related remote CICS region
  • The APPLID of another CICS system
REMOTEName(name) | Applicable only for remote terminals. Names the remote terminal. Necessary only if it differs from the local terminal name.
Associated Printers
PRINTER(name) | Identifies the printer used for handling print requests. This printer must be owned by the system that owns the terminal. name can be up to four characters in length.
PRINTERCopy(No|Yes) | Indicates whether or not the hardware copy feature (using the printer defined for this terminal) is used for print requests issued from this terminal.
ALTPRINTEr(name) | Identifies the printer used for handling print requests if the printer specified in PRINTER(name) is unavailable. This printer must be owned by the system that owns the terminal. name can be up to four characters in length.
ALTPRINTCopy(No|Yes) | Indicates whether or not the hardware copy feature (using the alternate printer defined for this terminal) is used for print requests issued from this terminal.
Operator Defaults
OPERId(code) | Specifies an operator ID used for routing messages. Specify this for a terminal that cannot be signed on, such as a printer. If you specify an operator ID for a terminal that can be signed on, it is overridden by the operator ID specified in the user's sign-on table entry. Up to three alphanumeric characters.
OPERPriority(number) Specifies the operator priority for transactions run from this terminal. Specify this for a terminal that cannot be signed on, such as a printer. If you specify it for a terminal that can be signed on, it is overridden by the operator priority specified in the user's sign-on table entry. Defaults to 0(zero). Operator priority is one factor in determining a transaction's execution priority, which is the sum of:

Terminal priority

Transaction priority

Operator priority (this field)

The sum cannot be greater than 255.

Preset Security
Userid(name) | Specifies a user ID to be associated with the terminal. Mandatory if no sign-on takes place on the connection.
Natlang(E|K) Specifies the national language in which messages are sent over the connection:

E: English

K: Kanji

Terminal Usages
Transaction(name) | Names the only transaction that users can run from this terminal, apart form print and paging requests. Optional. If not specified, users can run any transaction from this terminal.
Termpriority(number) Specifies the priority for transactions run from this terminal. Defaults to 0(zero). Terminal priority is one factor in determining a transaction's execution priority, which is the sum of:

Terminal priority (this field)

Transaction priority

Operator priority

The sum cannot be greater than 255.

Inservice(Yes|No) | Indicates whether or not this terminal is in service; that is, whether transactions can be initiated and messages sent.
Session Security
Securityname(name) | The security name of the terminal. Required only if the terminal is owned by a remote system and the connection method is APPC. Can be up to eight alphanumeric characters from the set A through Z, 0 through 9, $, @ and #.
ATtachsec(Local|Identify|Verify|Persistent|Mixedpe) The level of security required when a user issues an attach request from this terminal:

Local: the authority of the user is taken to be that of the link

Identify: Incoming attach requests must specify a user ID

Verify: Incoming attach requests must specify both a user ID and a password

Persistent: The first attach request must specify both a user ID and a password, but subsequent attach requests require only a user ID

Mixedpe: Incoming attach requests may specify either Identify or Persistent

  • Example
Parent topic: CICS Resource Definitions


Example

DEFINE TERMINAL(T001) GROUP(SAMPGRP)
DESCRIPTION(Sample terminal definition)
       AUTINSTMODEL(NO) TYPETERM(3270) NETNAME(NET0001) PRINTER(PRN2)
       PRINTERCOPY(YES) ALTPRINTER(PRN3) ALTPRINTCOPY(YES)
       OPERPRIORITY(0) USERID(P901) NATLANG(E) TERMPRIORITY(68)
       INSERVICE(YES) ATTACHSEC(LOCAL)
Parent topic: DEFINE TERMINAL
Related information
Resource Definitions


DEFINE TRANCLASS

Definition Attributes

Keyword (default values in bold) | Description
TRANClass(name) | Names the transaction class. Mandatory. name can be up to eight alphanumeric characters in length. Do not specify a transaction class name of DFHTCL00, as that name is reserved for transactions that do not belong to any particular class.
Group(groupname) | Names the group the transaction class definition belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support uses that prefix for system groups
Description(text) | Describes the resource. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
Maxactive(number) | The maximum number of transactions in this transaction class that are allowed to be active. Specify a number in the range 0 to 999.
PURGETHRESH(No|number) Defines a limit to the number of transactions queuing for this transaction class. After this limit is reached, transactions are purged. Specify a threshold:
No
The queue size is unlimited.
Number
The queue size is restricted to number. Specify a size in the range 1 to 1000000.
Parent topic: CICS Resource Definitions


DEFINE TRANSACTION

Defines the attributes of a transaction.

General

Keyword (default values in bold) | Description
TRANSaction(name) | Names the transaction. Mandatory. name can be up to four alphanumeric characters in length. Do not specify a transaction name starting with C, as Mainframe Subsystem Support uses that prefix for system transactions.
Group(groupname) | Names the group the transaction definition belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support uses that prefix for system groups
DEscription(text) | Describes the file. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
PROGram(name) | Program driven by this transaction.
TWasize(number) | Size of transaction work area, between 0 and 32767.
STAtus(Enabled|Disabled) Indicates whether or not the transaction is accessible when the region is started:
Enabled
The transaction is accessible when the region starts up
Disabled
The transaction cannot be used until it is specifically enabled using the transaction CPMT.

Remote Attributes

Keyword (default values in bold) | Description
DYnamic(No|Yes) Indicates whether or not the transaction can be dynamically routed to a remote region:
Yes
The transaction can be dynamically routed to a remote region
No
Creates a remote definition if REMOTESystem(name) is present; creates a local definition if it is not
REMOTESystem(name) Applicable only for remote transactions. Specifies the ID of the remote system that runs the transaction. This must correspond to either:
  • The Local SYSID field in the SIT used to run the related remote Mainframe Subsystem Support region
  • The APPLID of another CICS system
REMOTEName(name) | Applicable only for remote transactions. Names the remote transaction. Necessary only if it differs from the local transaction name.

Scheduling

Keyword | Description
PRIOrity(number) | Specifies the priority for this transaction. Defaults to 0(zero). Transaction priority is one factor in determining a transaction's execution priority, which is the sum of: Terminal priority Transaction priority (this field) Operator priority The sum cannot be greater than 255.
TRANClass(DFHTCL00|tranclass) | Specifies the name of the transaction class to which the transaction belongs. The reserved name DFHTCL00 is used to indicate that the transaction does not belong to any transaction class.

Recovery

Keyword (default values in bold) | Description
DTimout(No|0|hundredthsOfASecond) Specifies the deadlock timeout, that is, the period after which the transaction is terminated if it has been suspended.
NO
No deadlock timeout
0
Use system (SIT) deadlock timeout value
hundredthsOfASecond
The length of the timeout in hundredths of a second. The maximum value is 408000.
DUmp(No|Yes) | Indicates whether or not Mainframe Subsystem Support produces a program dump if this transaction abends.
Runaway(SYSTEM|0|hundredthsOfASecond) The time to allow a task to control the processor before it is assumed to be looping and therefore purged.
SYSTEM
Use system (SIT) value
0
No deadlock timeout
hundredthsOfASecond
On this system, must be a value between 100 and 270000. If less than 100 (one second), changes are ignored.
Note: That the mainframe allows 50 hundredths of a second.
TRACe(Yes|No|Special) Indicates tracing options for this transaction:
Yes
The transaction is traced
No
The transaction is not traced
Special
Not currently supported

Indoubt Attribute

Keyword (default value in bold) Description
INdoubt(Backout|Commit|Wait) Indicates the action to be taken if this transaction abends during syncpoint or abend processing:
Backout
The effects of the transaction are backed out using SYNCPOINT ROLLBACK (For this to work, you must also set backwards recovery on for any file used by the transaction.)
Commit
Any changes are committed
Wait
Critical resources are locked until the session has recovered and are then backed out or committed in step with the remote system

Security

Keyword (default values in bold) | Description
CMDSEC(No|Yes) | Indicates whether or not security checking is enabled for CICS command operations.
RESSec(No|Yes) | Indicates whether or not the transaction program performs resource security checking by comparing a user's resource keys (defined in the user's entry in the sign-on-table) with the keys enabled for a particular resource.
TRANSec(keys) Specifies one or more indicators, each corresponding to one of the 64 security keys for this transaction.

A user has access to a particular transaction only through a matching key as defined in his sign-on table entry. To toggle a key on you specify its number here. By default all keys are toggled off.

You code the keys as a comma-separated list of individual numbers and ranges separated by hyphens. For example, to toggle the keys 1 to 5 and 10 on, code TRANsec(1-5,10).

RSL(keys) (RSL stands for Resource Security Level.) Specifies one or more indicators, each corresponding to one of the 24 resource keys for this transaction.

A user has access to a particular resource only through a matching key as defined in his sign-on table entry. To toggle a key on you specify its number here. By default all keys are toggled off.

You code the keys as a comma-separated list of individual numbers and ranges separated by hyphens. For example, to toggle the keys 1 to 5 and 10 on, code RSl(1-5,10).

Micro Focus Extensions

Keyword (default values in bold) | Description
_CATEGORY(No|0|3) | A value of “3” specifies an IBM Category 3 Transaction. These transactions have no security checking. Therefore, transactions in this category are allowed for all users, and no authorization calls are made. An example of this type of transaction is CESN.
_Inboundtp(No|Yes) | Indicates whether or not registry entries to allow inbound transactions are created.
_Screen(Default|Alternate) | Indicates the screen size is used by the transaction. Both sizes are defined in the Typeterm definition for the terminal in use at the time.
_Uctran(Yes|No) | Indicates whether or not any data received by the transaction is automatically folded to upper case
_Timethold(SYSTEM|0|seconds) The time to wait for a transaction to complete before triggering a monitoring event.
SYSTEM
Use system (SIT) value.
0
No monitoring event.
seconds
Maximum time is 65333 seconds.
_Rtimeout(SYSTEM|0|seconds) The time to wait for input, after which the terminal will automatically sign off the user.
SYSTEM
Use system (SIT) value.
0
No timeout.
seconds
Maximum time is 4080 seconds.
  • Example
Parent topic: CICS Resource Definitions


Example

DEFINE TRANSACTION(TRNX) GROUP(SAMPGRP)
DESCRIPTION(Sample PCT entry)
       PROGRAM(ABP0001A) TWASIZE(1024) STATUS(ENABLED) DYNAMIC(YES)
       PRIORITY(100) DTIMOUT(NO) INDOUBT(COMMIT) DUMP(YES) TRACE(YES)
       RESSEC(NO) TRANSEC(01,09-10,15-20,25,30,53-59)
       RSL(02,07-10,15,24)

DEFINE TRANSACTION(TRNX) GROUP(SAMPGRP)
DESCRIPTION(Sample PCT entry)
       PROGRAM(ABP0001A) TWASIZE(1024) STATUS(ENABLED) DYNAMIC(YES)
       PRIORITY(100) DTIMOUT(NO) INDOUBT(COMMIT) DUMP(YES) TRACE(YES)
       RESSEC(NO) TRANSEC(01,09-10,15-20,25,30,53-59)
       RSL(02,07-10,15,24) _SCREEN(DEFAULT) _UCTRAN(YES) _INBOUNDTP(NO)
Parent topic: DEFINE TRANSACTION
Related information
Resource Definitions


DEFINE TDQUEUE

Defines the attributes of a transient data queue.
Keyword | Description
TDqueue(name) | Names this queue. Mandatory. name can be up to four alphanumeric characters, the first of which must be aletter other than C.
Group(groupname) | Names the group the queue belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system groups.
DESCription(text) | Describes the transient data queue. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
TYPE(INTra | Extra | INDirect | INTRDR) Specifies the type of this queue:

Intra: The contents of the queue are accessible only to transactions and are temporary

Extra: The contents of the queue are made available to non-CICS programs, or data is made available from non-CICS programs

INDirect: An alias that points to another queue, which may be of any type

INTRDR: Specifies the internal reader to which CICS applications can direct a JCL job stream for execution by the JCL engine.

Intrapartition Queue Parameters
Atifacility(Terminal|blank)) (Intrapartition queues). Indicates the type of destination the queue represents:

Terminal: the transient data queue is associated with a terminal, which is specified in Facilityid(name).

RECOVstatus(No|Physical|Logical) | (Intrapartition queues). Indicates whether or not the queue is recoverable. If you specify that the queue is recoverable (physical and logical are synonymous), you must also specify _FILESHAREID. This is because MSS recovery is handled by Fileshare.
Facilityid(name) | (Intrapartition queues). Specifies the terminal ID if Atifacility is set to Terminal. If unspecified defaults to the queue name. A terminal definition must exist.
TRAnsid(name) | (Intrapartition queues). Specifies the name of the transaction to be run when the queue reaches the level specified in Triggerlevel(number)
TRIggerlevel(number) | (Intrapartition queues). Specifies the number of data records to be accumulated in the queue before the transaction specified in Transid(name) is run. A value of 0 means that the transaction is never run.
Extrapartition Queue Parameters
DSName(name) | (Extrapartition queues). Not used..
Opentime(Initial|Deferred) (Extrapartition queues). Indicates the initial status of the queue:

Initial: the queue is opened when the region starts up

Deferred: the queue is closed until it is required

TypeFile(Output|Input|Rdback) | (Extrapartition queues). Specifies whether the queue is for input, output, or may be read backwards.
RECORDSize(number) | (Extrapartition queues). Specifies the maximum length of records in this queue, in the range 0 through 32767
RECORDFormat(Fixed|Variable) (Extrapartition queues). Specifies the record format:

Fixed: the minimum record size is set to the same value as the maximum record size

Variable: the minimum record size is set to 1

Printcontrol(Asa|Machine) | (Extrapartition queues). Specifies the type of print control characters to be used. Optional.
Indirect Parameters
Indirectname(name) | Specifies the name of another transient data queue, which must be defined
Remote Parameters
REMOTEName(name) | Applicable only for remote transient data queues. Names the remote queue. Necessary only if it differs from the local file name. The queue must be defined on the remote system.
REMOTESystem(name) | Applicable only for remote transient data queues. Specifies the ID of the remote system that holds the file. This must correspond to the Local SYSID field in the SIT used to run the related remote region.
Micro Focus Extensions
_Status(Enabled|Disabled) Effective only for queues owned by the local region. Specifies whether this queue is accessible when the region is started.

Enabled: accessible when the region starts up

Disabled: not accessible when the region starts up

_Minrecsize(number) | (Extrapartition queues). Specifies the minimum length of records in this queue. Must be less than or equal to RECORDSize. If this is not specified, MSS deduces it from RECORDFormat.
_FILEShareid(name) | Specifies the Fileshare server on which this queue resides
_PCfiletype(Normal|Lineseq) | Indicates the type of PC file to be created to hold the queue. Choose Lineseq if you want to edit the file.
_FILEName(name) | (Extrapartition queues). Specifies the name of the file that holds this queue. Do not include the file extension. Defaults to dfhxdddd.tdq where dddd is the four-character name of the queue as specified in Tdqueue(name).
_PAth(path) | (Extrapartition queues). Specifies the path of the file that holds the queue if you want to override the default.
_FILEExt(extension) | Specifies the extension of the file that that holds the queue if you want to override the default, which is .tdq
_Rsl(keys) | Specifies one or more indicators, each corresponding to one of the 24 resource keys for this queue. A user has access to a particular resource only through a matching key as defined in his sign-on table entry. To toggle a key on you specify its number here. By default all keys are toggled off. You code the keys as a comma-separated list of individual numbers and ranges separated by hyphens. For example, to toggle the keys 1 to 5 and 10 on, code Rsl(1-5,10).
  • Examples
Parent topic: CICS Resource Definitions


Examples

DEFINE TDQUEUE(A042) GROUP(SAMPGRP)
DESCRIPTION(Sample extrapartition DCT)
       TYPE(EXTRA) DDNAME(A042) OPENTIME(INITIAL) TYPEFILE(OUTPUT)
       RECORDFORMAT(VARIABLE) RECORDSIZE(500) BLOCKFORMAT(UNBLOCKED)
       REMOTENAME(P908) REMOTESYSTEM(SYSB)
DEFINE TDQUEUE(D010) GROUP(SAMPGRP)
DESCRIPTION(Sample intrapartition DCT)
       TYPE(INTRA) RECOVSTATUS(NO) TRANSID(TTAB) TRIGGERLEVEL(25)
DEFINE TDQUEUE(K022) GROUP(SAMPGRP)
DESCRIPTION(Sample extrapartition DCT)
       TYPE(EXTRA) DDNAME(K022) OPENTIME(INITIAL) TYPEFILE(OUTPUT)
       RECORDFORMAT(FIXED) RECORDSIZE(100) BLOCKFORMAT(UNBLOCKED)
DEFINE TDQUEUE(S030) GROUP(SAMPGRP)
DESCRIPTION(Sample indirect Q)
       TYPE(INDIRECT) INDIRECTNAME(D025)

DEFINE TDQUEUE(A042) GROUP(SAMPGRP)
DESCRIPTION(Sample extrapartition DCT with MF extensions)
       TYPE(EXTRA) DDNAME(A042) OPENTIME(INITIAL) TYPEFILE(OUTPUT)
       RECORDFORMAT(VARIABLE) RECORDSIZE(500) BLOCKFORMAT(UNBLOCKED)
       REMOTENAME(P908) REMOTESYSTEM(SYSB) _STATUS(ENABLED)
       _MINRECSIZE(26) _FILESHAREID(CICFSHRA) _PCFILETYPE(NORMAL)
       _FILENAME(ac116bx) _PATH(x:\frp\cicsa\) _FILEEXT(dct)
       _RSL(01,03,05,09-15)
DEFINE TDQUEUE(D010) GROUP(SAMPGRP)
DESCRIPTION(Sample intrapartition DCT with MF extensions)
       TYPE(INTRA) RECOVSTATUS(NO) TRANSID(TTAB) TRIGGERLEVEL(25)
       _STATUS(ENABLED)
DEFINE TDQUEUE(S030) GROUP(SAMPGRP)
DESCRIPTION(Sample indirect Q with MF extensions)
       TYPE(INDIRECT) INDIRECTNAME(D025) _STATUS(ENABLED)
Parent topic: DEFINE TDQUEUE
Related information
Resource Definitions


DEFINE TYPETERM

Defines the attributes for a set of terminals that have similar characteristics.
Keyword | Description
TYpeterm(name) | Names this terminal type. Mandatory. name can be up to four alphanumeric characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #.
Group(groupname) | Names the group the terminal type definition belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system groups.
DEScription(text) | Describes the terminal type. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
Resource Type
DEVice(3270|3270P) Specifies the device type:

3270: display

3270P: printer

SHippable(No|Yes) Indicates whether or not this definition can be shipped to a remote system if a device of this type attempts to initiate a remote transaction.

Yes: the terminal definition can be shipped. It is not necessary for the terminal definition to be installed on the remote system.

No: the terminal definition cannot be shipped. You must ensure that the terminal definition is installed on the remote system.

Mapping Properties
PAGesize(rows,columns) | Specifies the page size for the terminal type being defined. Page size is defined as rows, in the range 0 through 999, and columns, in the range 0 through 999. The default is 24 by 80.
ALTPage(rows,columns) | Specifies the page size for the terminal type being defined, if you have specified an alternate screen size (none-default values for ALTSCreen). Alternate page size is defined as rows, in the range 0 through 999, and columns, in the range 0 through 999. The default is 24 by 80. Unexpected results may occur if the number of columns is not the same as the number of columns you specify for alternate screen size. Defaults to the values specified in PAGesize
OBOperid(No|Yes) | Indicates whether or not MSS uses the outbound operator identifiers to support the BMS routing facilities required by this terminal type definition.
Device Properties
DEFscreen(rows,columns) | Specifies the default screen size for the 3270 terminal type being defined. This is the screen size that is used when a transaction definition specifies a default screen. Screen size is defined as rows, in the range 0 through 999, and columns, in the range 0 through 999. The default is 24 by 80. There is no validity checking; incorrect sizes may lead to unpredictable behavior.
ALTSCReen(rows,columns) | Specifies the alternate screen size for the 3270 terminal type being defined. This is the screen size that is used when a transaction definition specifies an alternate screen. Screen size is defined as rows, in the range 0 through 999, and columns, in the range 0 through 999. The default is 24 by 80. There is no validity checking; incorrect sizes may lead to unpredictable behavior.
APLKybd(No|Yes) | Indicates whether or not the terminal type has the APL keyboard feature
AUDiblealarm(No|Yes) | Indicates whether or not the terminal type has the audible alarm feature
COLor(Yes|No) | Indicates whether or not the terminal type has the color feature, allowing colors to be selected for individual fields
COPy(No|Yes) | Indicates whether or not the terminal type has the copy feature
DUalcasekybd(No|Yes) Indicates which type of keyboard the terminal type has:

Yes: the terminal has a typewriter keyboard

No: the terminal has an operator console keyboard

Both types of keyboard transmit both upper-case and lower-case data.

EXtendedds(Yes|No) Indicates whether or not the terminal type supports extensions to the 3270 data stream:

Yes: extensions are supported. You must specify Yes if you also specify yes for Color or Hilight.

No: extensions are not supported.

HIlight(Yes|No) | Indicates whether or not the terminal type has the extended highlight feature, allowing individual fields or characters to be displayed in bold, reverse video, or blinking
Katakana(No|Yes) | Indicates whether or not the this terminal type is a Katakana terminal type. Katakana terminals do not support mixed case output. Upper-case characters appear as upper-case English, but lower-case characters appear as Katakana characters.
Lightpen(No|Yes) | Indicates whether or not the terminal type has the light pen selector feature. MSS emulates this feature using mouse clicks.
PRIntadapter(Yes|No) | Indicates whether or not output BMS screens with the PRINT option set on are to be copied automatically to an attached printer.
PROgsymbols(No|Yes) | Indicates whether or not the terminal type supports the programmed symbol facility. This facility allows you to use a maximum of six sets of 191 characters.
OUtline(No|Yes) | Indicates whether or not the terminal type supports field outlining
SOsi(No|Yes) | Indicates whether or not the terminal type supports mixed EBCDIC and DBCS fields
CGcsgid(num1,num2) | Specifies the coded graphic character set global identifier (CGCSGID) that enables transaction programs to determine what character set is supported by this terminal. Defaults to 0,0, which means that the terminal type does not support this feature. num1 is the graphic character set global identifier (GCSGID) and num2 is the code page global identifier (CPGID).
Session Properties
AScii(No|7|8) Specifies whether or not this terminal type has an ASCII feature:

No: the terminal type does not have an ASCII feature

7: Terminals of this type are ASCII-7 terminals. All outbound data is translated to 7-bit ASCII, and all inbound data is translated to EBCDIC

8: Terminals of this type are ASCII-8 terminals. All outbound data is translated to 8-bit ASCII, and all inbound data is translated to EBCDIC

SENdsize(number) | Specifies the size, in bytes, of the receive buffer of a terminal of this type. This represents the maximum amount of data that the terminal can receive, and depends on the capability of the device. Considerations of line quality may lead you to specify a buffer size that is less than the terminal type's maximum buffer size. A message longer than the receive buffer is broken into as many request units as are necessary. Defaults to 0 (zero). If you specify a zero buffer size, the message is not broken up; the whole message is presented.
RECEivesize(number) | Specifies the maximum size, in bytes, of a request unit that can satisfy a receive request. The value you specify may be rounded down.
Diagnostic Display
ERRLastline(No|Yes) Indicates whether or not error messages are displayed at the bottom of the screen:

Yes: an error message is displayed at the bottom of the screen, starting at a position that allows the entire message to be shown at once. If messages are received in quick succession, an earlier message may be overwritten before the user has time to read it. Messages displayed in this way may have the additional attributes specified in ERRIntensity, ERRColor and ERRHilight.

No: an error message is displayed at the current cursor position, and without any additional attributes.

ERRIntensify(No|Yes) | Indicates whether or not an error message is displayed in an intensified field (bold). A setting of Yes takes effect only if ERRLastline is set to Yes.
ERRColor(NO|Blue|Red|Pink|Green|

Turquoise|Yellow|Neutral)

Specifies the color in which error messages are to be displayed on a terminal of this type. A setting other than NO takes effect only if ERRLastline is set to Yes.
ERRHilight(No|Blink|Reverse|

Underline)

Specifies the type of highlighting to be used for error messages displayed on a terminal of this type. A setting other than No takes effect only if ERRLastline is set to Yes.
Operational Properties
AUTOConnect(No|Yes) Indicates whether or not a session with the terminal is established when the region starts up:

Yes: a session is established when the region starts up

No: a session is established when the user signs on at the terminal

ATi(No|Yes) | Indicates whether or not a transaction can be automatically initiated on this terminal. If you specify ATi(No), you should specify TTi(Yes) to allow users to initiate transactions.
TTi(Yes|No) | Indicates whether or not users can initiate transactions at this terminal. If you specify TTi(No), you should specify ATi (Yes) to allow transactions to be automatically initiated.
CReatesess(No|Yes) Indicates whether or not a session can be initiated from a terminal of this type:

Yes: EXEC START requests and Automatic Transaction Initiation (ATI) requests are allowed to create sessions automatically

No: EXEC START requests and Automatic Transaction Initiation (ATI) requests are not allowed to create sessions automatically. Such requests are queued or rejected if a session has not been established.

Nepclass(number) | Specifies the transaction class of the node error program. Defaults to 0 (zero), which indicates that the default node error program is to be used.
Signoff(No|Yes) Indicates whether or not a terminal of this type is to be automatically signed off in the absence of user input:

Yes: the terminal is to be automatically signed off after a period of no user input; the length of this period is specified in the Timeout field of the user's entry in the sign-on table.

No: the terminal is not automatically signed of in the absence of user input.

Message Receiving Properties
ROutedmsgs(No|Yes) Indicates whether or not messages are routed to a terminal of this type by the EXEC CICS ROUTE command:

Yes: BMS routes to this terminal messages that are destined for all terminals, as well as messages destined for this terminal

No: no messages are routed to this terminal, even if they are specifically destined for this terminal

LOGOnmsg(No|Yes) Indicates whether or not the transaction that displays the logon message will be initiated when this terminal is connected:

Yes: the logon transaction is initiated when a session is established and displays the logon message on the terminal. Automatic Transaction Initiation (ATI) is used to start the transaction, so you must specify ATi(Yes). The transaction competes with any other ATI transactions for use of the terminal. If you specified ErrLastline(Yes), the logon message does not overwrite any error message currently displayed.

No: the logon transaction is not initiated when a session is established.

Application Features
BUildchain(No|Yes) Indicates whether or not MSS is to reassemble request units into complete messages before passing data from a terminal of this type to a transaction program:

Yes: MSS reassembles request units into a complete message before passing it to a transaction program.

No: messages are received by the transaction program in individual request units.

USerarealen(number) | Specifies the size, in bytes, of the user area of a terminal of this type. Defaults to 0 (zero).
Ioarealen(min,max) Specifies the minimum and maximum sizes, in bytes, of the terminal I/O area to be passed to a transaction program when it issues a RECEIVE. If you specify min, a terminal I/O area of at least that size is passed to the transaction program. If you specify both values and a message longer than min but shorter than max is received, then a terminal I/O area of the maximum size is passed to the transaction program. A message longer than max causes the node abnormal condition program to send an exception response to the terminal. Defaults to 0,0.

If you specify ATi(Yes), you must specify a terminal I/O area of at least one byte.

UCtran(No|Yes|Tranid) Indicates whether or not data entered in lower case is to be translated to upper case:

Yes: data input in lower case is translated to upper case

No: data input in lower case is not translated to upper case

Tranid: transaction identifiers input in lower case are translated to upper case; not other input data is translated

Recovery
RECOVOption(Sysdefault|Clearconv|

Releasesess|Uncondrel|None)

Specifies how MSS recovers the session and returns the terminal to normal service:

Sysdefault: MSS selects the best recovery strategy based on session activity and the characteristics of the terminal

Clearconv: MSS sends a CLEAR request to reset the conversation state, or an UNBIND request if the session does not support the CLEAR request. MSS sends the CLEAR or UNBIND request only if the session was busy.

Releasesess: MSS sends an UNBIND request to clear the active session, if the session was busy.

Uncondrel: MSS sends an UNBIND request to clear the active session, whether or not the session was busy

None: the terminal session is not automatically recovered. If you specified AUTOConnect(Yes), the terminal is automatically reconnected

RECOVNotify(None|Message|

Transaction)

Specifies how the user is notified of system recovery:

None: the user is not notified

Message: a message is displayed on the terminal. The terminal must be capable of displaying BMS maps, and you must have specified ATi(Yes)

Micro Focus Extensions
_Featurebuff(No|Yes) Indicates whether or not BMS buffers formatted data streams that are sent to a terminal of this type:

Yes: When an application issues a series of SEND TEXT PRINT commands, MSS sends a page to the terminal only when it is full

No: When an application issues a series of SEND TEXT PRINT commands, MSS sends a page to the terminal for every command issued, filling up the page by appending blank lines if necessary

  • Example
Parent topic: CICS Resource Definitions


Example

DEFINE TYPETERM(TT01AA01) GROUP(SAMPGRP)
DESCRIPTION(Sample terminal type definition)
       DEVICE(3270) SHIPPABLE(NO) PAGESIZE(24,80) ALTPAGE(24,80)
       OBOPERID(NO) DEFSCREEN(24,80) ALTSCREEN(24,80) APLKYBD(NO)
       APLTEXT(NO) AUDIBLEALARM(NO) COLOR(YES) COPY(NO)
       DUALCASEKYBD(NO) EXTENDEDDS(YES) HILIGHT(YES) KATAKANA(NO)
       LIGHTPEN(NO) PROGSYMBOLS(NO) FORMFEED(NO) OUTLINE(NO) SOSI(NO)
       CGCSGID(0,0) ASCII(NO) SENDSIZE(0) RECEIVESIZE(0)
       ERRLASTLINE(NO) ERRINTENSIFY(NO) ERRCOLOR(NO) ERRHILIGHT(NO)
       AUTOCONNECT(NO) ATI(NO) TTI(YES) CREATESESS(YES) NEPCLASS(0)
       SIGNOFF(NO) ROUTEDMSGS(NONE) LOGONMSG(NO) BUILDCHAIN(NO)
       USERAREALEN(0) IOAREALEN(0,0) UCTRAN(NO) RECOVOPTION(SYSDEFAULT)
       RECOVNOTIFY(NONE)
Parent topic: DEFINE TYPETERM
Related information
Resource Definitions


DEFINE _SIGNON

Defines user IDs and their level of access security to Enterprise Server resources.
Keyword | Description
Description(text) | Describes the sign-on record. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
_Password(password) The password that the user must supply to sign on to an enterprise server session.

Format: up to eight characters.

_OPIdent(name) An ID associated with the terminal.

Format: up to three alphanumeric characters.

_RSlkey(key,key1-key2) Specifies the resource keys owned by the user. A comma-separated list, each item in which may be any of the following:
nn
Toggle the specified resource key (nn is in the range 1 to 24).
mm-nn
Toggle resource keys in the range mm to nn inclusive (mm and nn are in the range 1 to 24).
_SCtykey(key,key1-key2) Specifies the security keys owned by the user. A comma-separated list, each item in which may be any of the following:
nn
Toggle the specified security key (nn is in the range 1 to 64).
mm-nn
Toggle security keys in the range mm to nn inclusive (mm and nn are in the range 1 to 64).
_USerkey(key,key1-key2) Specifies the surrogate keys owned by the user. A comma-separated list, each item in which may be any of the following:
nn
Toggle the specified surrogate key (nn is in the range 1 to 24).
mm-nn
Toggle surrogate keys in the range mm to nn inclusive (mm and nn are in the range 1 to 24).
_Timeout(minutes) Specifies the time, in minutes, for which the user will remain logged on to theTransaction System without initiating a transaction. A value of 0 means that the user will remain logged on indefinitely.

Format: 0 to 60.

_OPPrty(value) Specifies the priority of transaction programs started by this user. 0 is the highest priority, and 255 is the lowest. The priority of a transaction is the sum of:
  • The terminal priority
  • The transaction priority
  • The operator priority (this field)

This sum must not be greater than 255.

Format: 0 to 255.

_GRPPrefix(value) Controls this user's access to private group definitions. The user can only access groups whose names begin with the characters specified here.

You cannot specify a prefix that begins with "DFH".

If you do not specify a group prefix, the user cannot access any private group definitions.

Format: up to eight characters.

_GRPAccess(Update|Read|None) Specifies the type of access this user will be granted to group definitions.

The permissions specified here do not apply to groups whose name begins with "DFH".

In the case of private groups, the access granted here applies only to those groups whose name begins with the user's group prefix.

_PCtaccess(Update|Read|None) | Specifies the type of access this user will be granted to PCT definitions.
_FCtaccess(Update|Read|None) | Specifies the type of access this user will be granted to FCT definitions.
_PPtaccess(Update|Read|None) | Specifies the type of access this user will be granted to PPT definitions.
_DCtaccess(Update|Read|None) | Specifies the type of access this user will be granted to transient data queue/destination control table (DCT) definitions.
_SItaccess(Update|Read|None) | Specifies the type of access this user will be granted to SIT definitions.
_SNtaccess(Update|Read|None) | Specifies the type of access this user will be granted to sign-on table (SNT) definitions.
_TStaccess(Update|Read|None) | Specifies the type of access this user will be granted to temporary storage (TST) definitions.
_JCtaccess(Update|Read|None) | Specifies the type of access this user will be granted to journal control table (JCT) definitions.
_TTyaccess(Update|ReRead|None) | Specifies the type of access this user will be granted to terminal type (TTY) definitions.
_TRmaccess(Update|Read|None) | Specifies the type of access this user will be granted to terminal definitions.
_PLtaccess(Update|Read|None) | Specifies the type of access this user will be granted to program list table (PLT) definitions.
_SUpaccess(Update|Read|None) | Specifies the type of access this user will be granted to start-up list definitions.
_XLtaccess(Update|Read|None) | Specifies the type of access this user will be granted to XLT definitions.
_BAtaccess(Update|Read|None) | Specifies the type of access this user will be granted to batch processing.
_XAtaccess(Update|Read|None) | Specifies the type of access this user will be granted to XAT definitions.
_Imsaccess(Update|Read|None) | Specifies the type of access this user will be granted to IMS processing.
_JCLsubauth(Yes|No) | Specifies whether or not this user will be granted authority to submit JCL.

Example

DEFINE _SIGNON(FRED)
           DESCRIPTION(Fred’s system access)
       _PASSWORD(GUEST) _OPIDENT(SYS) _OPPRTY(255) _TIMEOUT(0)
       _RSLKEY(01-24) _SCTYKEY(01-64)
       _JCLSUBAUTH(NO) _GRPACCESS(UPDATE) _PCTACCESS(UPDATE)
       _FCTACCESS(UPDATE) _PPTACCESS(UPDATE) _DCTACCESS(UPDATE)
       _SITACCESS(UPDATE) _SNTACCESS(UPDATE) _TSTACCESS(UPDATE)
       _JCTACCESS(UPDATE) _TTYACCESS(UPDATE) _TRMACCESS(UPDATE)
       _PLTACCESS(UPDATE) _SUPACCESS(UPDATE) _XLTACCESS(UPDATE)
       _XATACCESS(UPDATE) _BATACCESS(UPDATE) _IMSACCESS(NONE)
Parent topic: CICS Resource Definitions


CICS Supplied Transactions

  • CAMX - Set Maximum Number of Servers
    Sets the maximum number of transaction servers for the region.
  • CDBG - Modify Debug Server
    Modifies a debug server.
  • CEBR - Browse Temporary Storage
    Examines the contents of records in temporary storage or transient data queues.
  • CENV - Show Active Configuration
    Displays the environment used by .
  • CESF - Sign Off
    Signs off from a terminal
  • CESN - Sign On
    Signs on to a terminal.
  • CFCR - Create a File
    Creates an empty file, if the file has previously been defined in the FCT.
  • CFLE, CFLI, CFLS - File Editor
  • CFMT - File Master Transaction
    Opens, closes, enables, disables or inquires on a file.
  • CGWY - Display the Status of and Start CCI Gateways
    Displays the status of CCI gateways and allows CCI gateways to be started.
  • CINQ - Inquire On ASSIGN Values
    Displays a list of all the ASSIGN command values and their settings.
  • CINS - Install a Resource Group
    Installs a resource or a group of resources.
  • CKQC - Start a CKTI monitor
    Starts the CKTI transaction, which monitors the named WebSphere MQ initiation queue.
  • CLOG - View the Console Log
    Allows you to view and search the console log in the same way as you can view and search the console log display of the Monitor Region tool. This is available for both multi-tasking and single-tasking systems.
  • CMAP - Display BMS Maps and Information
    CMAP displays the contents of a BMS map and displays information about the map and mapset.
  • CNCL - Release Copies of a Program
    Releases any existing copies of the specified called program from memory.
  • CPMT - Inquire and Set Program Attributes
    Displays the current attributes of the specified program for an inquire, and sets the specified program attribute.
  • CQIT - Shut Down a Region
    Shuts down a region.
  • CRTE - Start Transaction Routing
    Starts a transaction routing session to a remote system.
  • CRUN - Generic Run Program
    Invokes the specified program.
  • CSPG - Page Manipulation
    Manipulates pages of information produced by transactions where there is too much information to be displayed or printed at one time. You must have created the pages of information using BMS.
  • CSSF - End Transaction Routing
    Ends transaction routing session.
  • CTRA - Trace Activity
    Controls trace activity in Mainframe Transaction Option.
  • CWTO - Write to Operator
    Write to operator console.
  • EXIT - Sign Off Terminal Emulator
    Signs off and closes the terminal window.
Parent topic: Reference for MSS Deployment


CAMX - Set Maximum Number of Servers

Sets the maximum number of transaction servers for the region.

Syntax:

CAMX number

Notes:

The number must be in the range 1 through 999.

Parent topic: CICS Supplied Transactions


CDBG - Modify Debug Server

Modifies a debug server.

Syntax:

CDBG

Notes:

You do not enter any options on the command line. When you press Enter after CDBG, a screen is displayed showing details of the current debug server. You can:

  • Change the type of server from Term (for Terminal) to Tran (for Transaction) and vice versa. (You can't change the type of server if it is set to Generic.)
  • Change the resource that is being monitored.
Parent topic: CICS Supplied Transactions


CEBR - Browse Temporary Storage

Examines the contents of records in temporary storage or transient data queues.

Syntax:

CEBR

Notes:

You do not enter any options on the command line. When you press Enter after CEBR, a screen is displayed showing the contents of the queue CEBRname, where name is your terminal identifier.

If you want to display a different queue, either:

Enter the subcommand QUEUE with the queue identifier.

or:

Enter the queue identifier in the CEBR command line.

CEBR Subcommands:

The CEBR transaction has the following subcommands (the acceptable abbreviation is shown in upper case):

Option | Topic
BOTtom | Displays the last records in the TS queue (as many as fill the screen)
COLumn nnnn | Displays TS queue records starting at column nnnn
Find /string | Searches TS queue records for the character string string
GET xxxx | Takes the contents of the transient data queue named xxxx and puts it at the end of the displayed TS queue, so that you can browse its contents
LINE nnnn | Alters the display so that record nnnn -1 is at the top of the screen and record nnnn is the current record.
PURGE | Deletes the TS queue that you are browsing
PUT xxxx | Copies the TS queue being browsed to the TD queue named xxxx
Queue xxxxxxxxxxxxxxxx | Displays the contents of the TS queue named xxxxxxxxxxxxxxxx
TERMinal xxxx | Displays the contents of the TS queue named term-idxxxx, where term-id is your terminal identifier
Top | Starts the display at the first record in the TS queue

Restrictions:

The CEBR transaction works as it does on a mainframe, with minor exceptions. In the QUEUE subcommand, you cannot supply a queue name in hexadecimal. There are no PF key equivalents for subcommands.

Parent topic: CICS Supplied Transactions


CENV - Show Active Configuration

Displays the environment used by .

Syntax:

CENV

Notes:

A list of environment variables and their values is displayed on the screen.

Parent topic: CICS Supplied Transactions


CESF - Sign Off

Signs off from a terminal

Syntax:

CESF

Notes:

When the terminal emulator session is closed down, the sign-on screen appears.

Parent topic: CICS Supplied Transactions


CESN - Sign On

Signs on to a terminal.

Syntax:

CESN

Notes:

You do not enter any options on the command line. A screen appears when you enter the command, prompting you for:

Userid (1 to 8 characters)

Password (1 to 8 characters). Your password is not displayed on the screen when you type it in.

New password (1 to 8 characters). This field appears only if you have the authority to change your password.

Parent topic: CICS Supplied Transactions


CFCR - Create a File

Creates an empty file, if the file has previously been defined in the FCT.

Syntax:

CFCR fct-file-entry

Notes:

fct-file-entry is the name specified in the file option in the FCT. The file can be either a base file or an alternate index. It is created with all the related indexes.

A confirmation message shows you the base file characteristics and all the alternate keys that you specified. An error message is displayed if the file has not been created.

Parent topic: CICS Supplied Transactions


CFLE, CFLI, CFLS - File Editor

Syntax:

CFLE
CFLI [/Fcccccccc] [/Dfilename] [/Ccharset] [/Kkey]
CFLS

Entering the transaction name CFLE, CFLI, or CFLS on its own displays the main selection menu listing all the files that have FCT entries in the region.

You can select the file you want to edit from this list.

Parameters

[/Fcccccccc]
Displays only those file names that match the cccccccc specification. cccccccc can be 1 to 8 characters and is case sensitive. You can specify a '?' as a positional wildcard character. For example:
CFLE /FT

displays all file names beginning with 'T' and

CFLE /F??S

displays all file names whose third character is 'S'.

[/Dfilename]
Displays the edit screen for the filename specified and positions you on the first record. filename can be 1 to 8 characters and is case sensitive. For example:
CFLE /DTSTAKSDS

displays the edit screen for file TSTAKSDS positioned on the first record.

[/Ccharset]
Defines the character set of the file, A for ASCII (the default) or E for EBCDIC. For example:
CFLE /DTSTEKSDS /CE

displays the edit screen for file TSTEKSDS as an EBCDIC file.

[/Kkey]
Defines the key of the record at which the edit screen is positioned. key can be 1 to 64 characters and can be specified as character or hexadecimal.

For example:

CFLE /DTSTAKSDS /CE /K2222

or

CFLE /DTSTAKSDS /CE /KX'F2F2F2F2'

displays the edit screen for file TSTEKSDS as an EBCDIC file positioned at the record with key 2222.

If you specify both the /F and /D parameters, on leaving the edit screen the list of files defined by the /F parameter is displayed on the main selection screen.

Notes:

  • The CFLI transaction has no security restrictions and can be used by any user. It allows read access to local KSDS, ESDS, and RRDS files.
  • The CFLE transaction can be used only by a signed-on user (if security is turned on). It allows read and update access to local and remote KSDS, ESDS, and RRDS files. It also allows changes to the status of files in a similar way to the CFMT transaction.
  • The CFLS transaction has all the facilities of CFLE plus the ability to edit sequential files. It is installed in the group DFHOPER and cannot be used by any user when security is turned on. (You must copy the PCT entry to your own group and set the appropriate security keys for your installation.)
  • If, when using a TN3270 emulator to access CFLE, the F1 Help function does not behave correctly, you need to upgrade the resource definition file using the following command:
    caspcupg /dp=<resource-definition-path>
Parent topic: CICS Supplied Transactions


CFMT - File Master Transaction

Opens, closes, enables, disables or inquires on a file.

Syntax:

CFMT [OPen|CLose|ENable|DIsable|INquire|NAme] filename

Notes:

You must enter at least the first two letters of the option you choose.

The filename may contain wild card characters. A question mark denotes any single character, while a single asterisk denotes any number of characters. An asterisk can appear only at the end of the filename. Question marks and an asterisk can be combined, for example:

CFMT CL A??PP*

closes all files that start with "A" and have "PP" in character positions 4 and 5.

You can use the CEBR transaction to view the results of a CFMT transaction that uses wild cards in the filename.

Parent topic: CICS Supplied Transactions


CGWY - Display the Status of and Start CCI Gateways

Displays the status of CCI gateways and allows CCI gateways to be started.

Syntax:

CGWY

Notes:

You can use this transaction only in multi-tasking regions. It displays a screen listing the CCI gateways available and their status.

You can start any of the gateways by specifying '/' or 'S' next to the gateway and pressing Enter. Pressing F3 exits from the transaction.

Parent topic: CICS Supplied Transactions


CINQ - Inquire On ASSIGN Values

Displays a list of all the ASSIGN command values and their settings.

Syntax:

CINQ

Notes:

The ASSIGN command values and settings are listed in alphabetic order.

Parent topic: CICS Supplied Transactions


CINS - Install a Resource Group

Installs a resource or a group of resources.

Syntax:

CINS group-name

CINS resource-type(resource-id) GROUP(group-name)

Parameters:

resource-type | One of FILE, PROGRAM, TDQUEUE, TERMINAL, TRANSACTION, TRANCLASS, TYPETERM, TCPIPSERVICE, URIMAP, WEBSERVICE, PIPELINE, or DOCTEMPLATE. You must supply at least the portion of the type shown in bold/underlined, and it must be in upper case.
resource-id | The name of the resource
group-name | The name of the group the resource belongs to

Notes:

If the group is already installed, the existing definitions are replaced by those currently in the resource definition file (RDF). The group-name can be a maximum of eight characters. GROUP can be abbreviated down to G.

Output:

Results from the transaction are written to a temporary storage (TS) queue with a name of CEBR name, where name is the current terminal or facility ID. You can browse this queue with the supplied transaction CEBR. See CEBR - Browse Temporary Storage for more information.

Examples:

CINS MCOGROUP

This command will install all resources from the group MCOGROUP.

CINS F(ACCTFIL) G(TEST)

This command will install the file control table entry for ACCTFIL from the resource group TEST.

Parent topic: CICS Supplied Transactions


CKQC - Start a CKTI monitor

Starts the CKTI transaction, which monitors the named WebSphere MQ initiation queue.

Syntax:

CKQC [STARTCKTI initiation-queue-name]

Notes:

You must have configured WebSphere MQ for MSS before running this transaction. See Configuring Enterprise Server for IBM WebSphere MQ for more information.

You can invoke this transaction in a terminal window or in a program.

If you invoke CKQC in a terminal window, you need to enter only CKQC. A message then appears prompting you for the initiation queue name.

If you invoke CKQC in a program, you pass the command in an INPUTMSG or COMMAREA to the CICS utility dfhzckqc. If you invoke CKQC from a PLTPI program, it cannot use the INPUTMSG parameter; only the COMMAREA is available. For example:

ID DIVISION.
PROGRAM-ID. TESTCKQC.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
INPUT-OUTPUT SECTION.
DATA DIVISION.
FILE SECTION.
WORKING-STORAGE SECTION.
01  DATA-BUFF                    PIC X(80) VALUE
   'CKQC STARTCKTI TEST.INITQ'.
LINKAGE SECTION .
PROCEDURE DIVISION.
MODULE-ENTRY-POINT.
    EXEC CICS LINK
              PROGRAM ('DFHZCKQC')
              COMMAREA (DATA-BUFF)
              LENGTH (LENGTH OF DATA-BUFF)
    END-EXEC

    EXEC CICS RETURN
    END-EXEC
    GOBACK.
Parent topic: CICS Supplied Transactions


CLOG - View the Console Log

Allows you to view and search the console log in the same way as you can view and search the console log display of the Monitor Region tool. This is available for both multi-tasking and single-tasking systems.

Syntax:

CLOG

Notes:

Help that describes the function keys is available on each screen.

Parent topic: CICS Supplied Transactions


CMAP - Display BMS Maps and Information

CMAP displays the contents of a BMS map and displays information about the map and mapset.

Syntax:

CMAP [mapset-name [map-name]]

Parameters:

[mapset-name [map-name]]

If a mapset-name is specified, then a list of maps within the mapset is displayed. If, in addition, a map-name is specified, then that map is displayed.

If map-name is not specified, you can use wildcard characters ("?" and "*") within mapset-name to reduce the number of mapsets displayed.

Notes:

If no parameters are specified, or the parameters specified are not found, a list of mapsets found in the mapset directories is displayed. If a mapset contains .MOD files, the mapset name is displayed in white. If it contains .MST files, it is displayed in blue.

You can select an item in a list either by positioning the cursor, or by typing a slash "/" against the item, and pressing Enter. Selecting a mapset displays a list of the maps it contains. Selecting a map displays the map itself.

If a mapset appears more than once in the list, then CMAP always displays the first mapset.

Typing "i" against an item (mapset or map) and pressing Enter, displays information about the item.

Typing "d" against a mapset and pressing Enter deletes the mapset. A confirmation message is displayed. Press Enter to confirm the delete, press any other attention key to cancel it.

You can use F7-PgUp and F8-PgDn to page through lists that are more than one screen long.

Pressing Clear (or any attention key) returns to the previous higher level screen.

You can exit the transaction at any time by pressing F3.

Parent topic: CICS Supplied Transactions


CNCL - Release Copies of a Program

Releases any existing copies of the specified called program from memory.

Syntax:

CNCL program-name

Notes:

This transaction releases any existing copies of the specified called program from memory. (A called program is one that is not invoked through LINK or XCTL.) If a PPT entry exists for the program-name specified, an error message is displayed and the program is not released. (In this case you should use transaction CPMT NEWCOPY.) This transaction is valid only in an environment where logical cancel support is enabled in the COBOL run-time system.

Parent topic: CICS Supplied Transactions


CPMT - Inquire and Set Program Attributes

Displays the current attributes of the specified program for an inquire, and sets the specified program attribute.

Syntax

CPMT function program-name

Notes

The function is specified as one of:
  • NEwcopy
  • PHasein
  • DPlsubset
  • FUllapi
  • PRivate
  • SHared
  • ENabled
  • DIsabled
  • INquire
  • NAme-inquire

CEdf and NOCEdf are not supported.

For each function except INquire and NAme-inquire, CPMT issues an EXEC CICS SET PROGRAM command for the corresponding system programming API keyword.

For the INquire function, CPMT issues an EXEC CICS INQUIRE PROGRAM command, and displays the results.

For the NAme-inquire function, CPMT displays the fully qualified program name of the object loaded from disk for the associated program or table.

Parent topic: CICS Supplied Transactions


CQIT - Shut Down a Region

Shuts down a region.

Syntax:

CQIT [IMMED]

Notes:

If you specify IMMED, no programs specified in the PLTSD list in the SIT are executed. All existing tasks are canceled.

Parent topic: CICS Supplied Transactions


CRTE - Start Transaction Routing

Starts a transaction routing session to a remote system.

Syntax:

CRTE SYSID=sysid

Notes:

sysid is the system identifier of the remote system to which you want to connect. A message is displayed to confirm that the routing session has been started. You might need to sign on to the remote system before running any transaction. After this, you can enter the transaction identifier of the transaction you want to run.

Parent topic: CICS Supplied Transactions


CRUN - Generic Run Program

Invokes the specified program.

Syntax:

CRUN program

Notes:

The program is invoked through XCTL. You can use CRUN to execute a program without having to define an explicit PCT entry for it. CRUN is useful for testing a program, or for invoking a PLT-type program on an as-required basis.

Parent topic: CICS Supplied Transactions


CSPG - Page Manipulation

Manipulates pages of information produced by transactions where there is too much information to be displayed or printed at one time. You must have created the pages of information using BMS.
Note: BMS must be running in the system to act on the CSPG commands you enter.
  • CSPG getpage
    Retrieves a page.
  • CSPG getpageQ
    Displays the message identifiers and titles of logical messages queued for this terminal.
  • CSPG messchnyyyy
    Keeps the old pages from a transaction.
  • CSPG hmsgterm
    Erases a logical message, leaving the previous message displayed.
  • CSPG msgcopy
    Sends a copy of the page being displayed, as it appeared when initially transmitted, to another terminal.
Parent topic: CICS Supplied Transactions


CSPG getpage

Retrieves a page.

Syntax:

CSPG getpage[(x)] y [*ldc|*ALL][,hhhhhh]

Parameters:

getpage
The identification code you define for the retrieval transaction (1 to 7 characters)
(x)
For chaining messages. It indicates the level of the message you want to retrieve. You must include the parentheses. The value of x can be:
n | Message is at level n
+n | Message is at level n higher
-n | Message is at level n lower
C | Message is at current level (default)
L | Message is at last level
N | Message is at next level
P | Message is at previous level
y
The next thing you want to do with the message. It can be:
n | Display page n
+n | Display page n pages forward
-n | Display page n backward
C | Clear the screen and display current page again
L | Display the last page
N | Display the next page
P | Display the previous page
A | Only for auto-paging hard-copy terminals. Return the terminal to autopaging mode and output remaining pages.
*ldc
Reset the specified logical device code where you want to send the message to autopage.
*ALL
Reset all logical devices to autopage (if they are defined as such in the terminal definition).
hhhhhh
The identifier of an undelivered logical message you want to retrieve.
Parent topic: CSPG - Page Manipulation


CSPG getpageQ

Displays the message identifiers and titles of logical messages queued for this terminal.

Syntax:

CSPG getpageQ

Parameters:

getpage | The identification code you define for the retrieval transaction. (One to seven characters long.)
Q | Indicates that you want the identifiers of all of the logical messages directed to this terminal to be displayed.
Parent topic: CSPG - Page Manipulation


CSPG messchnyyyy

Keeps the old pages from a transaction.

Syntax:

CSPG messchnyyyy [parameters]

Parameters:

messchn | The defined message-chaining transaction identification code for your installation.
yyyy | The identifier of a transaction that produces data to be added to the message chain.
parameters | Any parameters transaction yyyy needs.
Parent topic: CSPG - Page Manipulation


CSPG hmsgterm

Erases a logical message, leaving the previous message displayed.

Syntax:

CPSG hmsgterm{A|B|C|H|R}[,hhhhhh]

Parameters:

msgterm | The transaction identifier of your message terminating transaction.
A | Terminates all logical messages directed to or currently being displayed on the terminal
B | Terminates the logical message currently being displayed on the terminal, and any logical messages chained to it.
C | Terminates the current logical message and any messages chained to it.
H | Terminates all logical messages chained to the message being displayed on the terminal. The page of the base message that was most recently displayed is redisplayed at the terminal.
R | Terminates all logical messages routed to the terminal. The page that was being displayed at the terminal is redisplayed.
hhhhhh | The 6-digit hexadecimal identifier of a specific, undelivered logical message to be erased. You can find out the message identifier using a page query command.

When termination is complete, you receive the message:

DFHTP4122 REQUESTED PURGE COMPLETE

Parent topic: CSPG - Page Manipulation


CSPG msgcopy

Sends a copy of the page being displayed, as it appeared when initially transmitted, to another terminal.

Syntax:

CSPG msgcopy tttt

Parameters:

msgcopy | The copy transaction identifier (one to seven characters long).
tttt | The identifier of the terminal to which the page is to be copied.

Comments:

A hard-copy terminal that is not defined as a paging terminal (one that displays pages when you request them) is an autopaging terminal (one that displays all pages without your intervention). You can temporarily designate an autopaging terminal as a paging terminal by using the NOAUTOPAGE option of the SEND PAGE command. If you do this the time the first page is to be displayed on the terminal, the terminal is temporarily treated as a paging terminal for the duration of the message. To stop this:

  1. Type P/A (reset terminal to autopaging status), indicating that all subsequent pages are to be displayed without further intervention.
  2. Type T/C (terminate current message). All pages from that logical message are purged, and the terminal is again put into autopaging status.

P/ is the paging transaction identifier, and T/ is the terminate transaction identifier.

You can use the message-switching transaction to direct output to other terminals.

When a terminal to which you have directed a message is in TRANSCEIVE status, and is not involved with a transaction, and is not displaying pages, CICS displays the first page of that message.

However, if the terminal is in TRANSACTION status, you can display the first page only of a waiting message by typing CSPG, CSPG P/1, or by typing simply P/1. Here, you are using P/ as a paging command. If no page is waiting, you get the following message:

DFHTP4104-NO PAGES WAITING TO BE DISPLAYED

Parent topic: CSPG - Page Manipulation


CSSF - End Transaction Routing

Ends transaction routing session.

Syntax:

CSSF

Parent topic: CICS Supplied Transactions


CTRA - Trace Activity

Controls trace activity in Mainframe Transaction Option.

Syntax:

CTRA

Notes:

You do not enter any options on the command line. A screen appears when the command is entered, which prompts for the following:

Activate trace facility, which can be set to Y(es) or N(O). Y activates trace for the system components marked with a Y. N stops all trace.

Overwrite existing file, which can be Y(es) or N(o). Y overwrites the existing trace file; N creates a new trace file.

Functions to trace lists the following functions. Y turns trace on for that function, N turns it off.

Storage control

Task Control

File Control

Dump Control

TS/TD Control

Interval Control

Journal Control

Table Management

Terminal Control

Communications

User Trace

Message

API

CCI

Pressing F3 saves the changes you have made; F12 discards them. Both function keys end the transaction.

Parent topic: CICS Supplied Transactions


CWTO - Write to Operator

Write to operator console.

Syntax:

CWTO message

Notes:

You can use this transaction only in a multi-tasking region.

If you do not type a message when you enter the transaction identifier, you are prompted for the message.

Parent topic: CICS Supplied Transactions


EXIT - Sign Off Terminal Emulator

Signs off and closes the terminal window.

Syntax:

EXIT

Notes:

When the terminal emulator closes down, the terminal is disconnected from Enterprise Server.

Parent topic: CICS Supplied Transactions


IMS Support in Enterprise Server

  • IMS DB system commands
    IMS DB system commands supported by Enterprise Server, which are a subset of all IMS DB commands.
  • IMS DB system command interfaces
    Lists the interfaces available for executing IMS DB system commands.
  • IMS Database Control (DBC) Commands
    Describes the IMS Database Control commands used with IMS database Forward and Automatic Backward Recovery.
  • IMS Tracing Flags
  • IMS-Specific Environment Variables
  • Non-discardable Messages (NDM) Interface Block
  • Standard User Exit Parameter List
Parent topic: Reference for MSS Deployment


IMS DB system commands

IMS DB system commands supported by Enterprise Server, which are a subset of all IMS DB commands.
/DIS
Syntax:
/DIS[PLAY] DB ALL | database1 [database2] ...
Syntax Rules:
  • This returns the current status of each of the named databases.
  • 1 to 16 databases can be specified or the “ALL” parameter.
  • ES-IMS only returns database status for those databases it knows about. ES-IMS accesses databases as they are accessed by application programs and system commands, so the list of "known" databases grows dynamically.
  • Database statuses::
    • UNKNOWN - The database name is not valid. There is no ACB defined for this DB.
    • NOTOPEN - The database is defined but has not been accessed.
    • OPEN - The database is currently being accessed by an application program.
    • CLOSED - The database has been opened but is not currently open.
    • STOPPED - The database is stopped and not available to MPP, BMP or CICS-DLI programs.
/STO
Syntax:
/STO[P] DB database1 [database2] ...
Sytax Rules:
  • The STOP command stops a database or a list of databases.
  • When a database is stopped, it is not accessible from MPP, BMP or CICS-DLI programs. The database is only accessible from IMSDBU or batch DLI programs.
  • This command is run synchronously. It will suspend until the database is closed and stopped.
/STA
Syntax:
/STA[RT] DB database1 [database2] ...
Syntax Rules:
  • The START command starts a database or a list of databases.
  • Use the START command to make the database available to online, BMP and CICS-DLI programs.
Parent topic: IMS Support in Enterprise Server
Related reference
IMS DB system command interfaces


IMS DB system command interfaces

You can execute IMS DB system commands using any of the following interfaces:

TN3270
  • Database commands can be entered via a TN3270 session connected to /IMS.
  • The response output from the command will be sent back to the terminal session.
ESMAC
  • DB commands can be entered via the ESMAC IMS Control panel.
  • The response output is sent back to the ESMAC panel.
JCL
  • DB commands can be entered via the IMSDBU JCL interface using the PARM parameter
  • The response output is sent back to the job in the SYSOUT DD for the job step.
  • Step condition code is set if command fails.
  • Sample JCL step
    //STEP01  EXEC PGM=MFDBUJCL,PARM='/DIS DB DEMO03DD'
//SYSOUT  DD SYSOUT=*
  • Only one command can be entered per JOB step.
Parent topic: IMS Support in Enterprise Server
Related reference
IMS DB system commands


IMS Database Control (DBC) Commands

Describes the IMS Database Control commands used with IMS database Forward and Automatic Backward Recovery.
/DBC RESUME
Restores a database to full IMS function, and starts it in "suspend" mode.

When DBC starts an IMS database in "suspend" mode, normal transactional processing is prohibited. DBC accepts only commands to recover, START, and STOP databases.

DBC starts an IMS database in "suspend" mode when, on startup, it finds one or more corrupt databases. This can happen when Automatic Backward Recovery was previously disabled.

Use /DBC RESUME after all affected IMS databases have been recovered.

/DBC RESUME FORCE
Restores a database to full IMS function even when the database has not been recovered.
CAUTION:
Transactions run as normal and could access both corrupt and intact databases.
/DBC STATUS
Displays the current status of IMS Database Control.
/DBC SUSPEND
Puts IMS DBC into "suspend" mode.
Parent topic: IMS Support in Enterprise Server


IMS Tracing Flags

A list of the IMS flags used in MSS tracing.

Flag | Description
api | Check this to indicate that MSS is to trace IMS DL/I API entry points.
cli | Check this to indicate that MSS is to trace IMS MPR, JES and SEP processing.
data | (Not used)
DB-thread | Check this to indicate that MSS is to trace lock management for IMS DB.
dbc | Check this to indicate that MSS is to trace IMS DB control processing.
ES-DB | Check this to indicate that MSS is to trace ES IMS DB processing.
ES-stg | Check this to indicate that MSS is to trace ES IMS memory management.
TM-thread | Check this to indicate that MSS is to trace lock management for IMS TM.
i/o | Check this to indicate that MSS is to trace IMS physical/virtual file I/O.
stg | Check this to indicate that MSS is to trace IMS dynamic memory allocation/freeing.
TM-buffer | Check this to indicate that MSS is to trace the buffer for IMS TM lock management.
sys | Check this to indicate that MSS is to trace miscellaneous IMS processing.
TM-ctl | Check this to indicate that MSS is to trace IMS TM control processing.
Parent topic: IMS Support in Enterprise Server


Non-discardable Messages (NDM) Interface Block

The contents of the NDM interface block are:

Field | Offset | Length | Picture | Description
NDMEYE | X'00' | 4 | pic x(4) | Eye catcher ( value = 'NDM').
NDMTRAN | X'04' | 8 | pic x(8) | Transaction that the application was processing when it abended. This transaction is associated with the input message pointed to by NDMMSGA.
NDMPSBN | X'0C' | 8 | pic x(8) | PSB associated with the application that abended.
NDMUSID | X'14' | 8 | pic x(8) | User ID.
NDMGRPNM | X'1C' | 8 | pic x(8) | Group name.
NDMUSIDI | X'24' | 1 | pic x(1) | Indicator for the contents of NDMUSID (v alue = ' U ' , meaning the contents is a user ID).
NDMSRCFL | X'25' | 1 | pic x(1) comp-x | Flag that indicates the origin of the input message (v alue = 0, meaning the origin is an LTERM).
NDMLTERM | X'26' | 8 | pic x(8) | Name of the originating LTERM.
 | X'2E' | 110 |  | Reserved.
NDMABEND | X'9C' | 4 | pic s9(9) comp | Abend code in system format 00sssuuu, where: sss = System abend code uuu = User abend code
NDMTSLCL | X'A0' | 8 |  | Local time stamp of the arrival of the input message in the system. NDMTSLCL contains NDMDLCL and NDMTLCL.
NDMDLCL | X'A0' | 4 | pic s9(7) comp-3 | Local date that the message arrived, in format YYYYDDDf, where: YYYY = Year DDD = Julian day f = X'F'
NDMTLCL | X'A4' | 4 | pic s9(7) comp-3 | Local time that the message arrived, in format HHMMSSTf, where: HH = Hours MM = Minutes SS = Seconds T = Tenths of seconds f = X'F'
 | X'A8' | 12 |  | Reserved.
NDMSPAA | X'B4' | 4 | pointer | Address of the SPA if the transaction in NDMTRAN is a conversational transaction, otherwise this field contains zeros. If the SPA is present, the format is as follows: LL|ZZZZ|Trancode|Data, where: LL = Two-byte length field that includes the length of LLZZZZ ZZZZ = Four-byte field that always contains zeros Trancode = Eight-byte field that contains the transaction code for the conversation or blanks Data = SPA user data
NDMMSGA | X'B8' | 4 | pointer | Address of the input message. If this field is zero, there is no message segment and the message can be a SPA segment only. The format is as follows: LL|ZZ|Data, where: LL = Two-byte length field that includes the length of LLZZ ZZ = Two-byte field that always contains zeros except for the last segment which contains X'FFFF' Data = Message segment data For a multi-segment message, the pattern is: NDMMSGA = address of first segment NDMMSGA+LL 1 = address of second segment NDMMSGA+LL 1 +LL 2 = address of third segment Etc.
NDMMSGL | X'BC' | 4 | pic s9(9) comp | Total length of the input message.
 | X'C0' | 20 |  | Reserved.
NDMABRSN | X'D4' | 4 | pic s9(9) comp | Abend reason code (if available).
NDMTRNST | X'D8' | 4 | pic s9(9) comp | Transaction status flag. Enterprise Server examines this field on return from the exit routine. The exit routine can set this field to any one of the following values: Value = 1 means do not stop the abended transaction. Value = 2 means do not send the DFS555I message. Value = 3 means do not stop the abended transaction and do not send the DFS555I message.
NDMDEST | X'DC' | 8 | pic x(8) | Name of the alternate destination set by the exit routine to which the input message is to be queued. Enterprise Server only examines this field if you pass back return code 16, otherwise Enterprise Server ignores this field.
Parent topic: IMS Support in Enterprise Server


Standard User Exit Parameter List

The contents of the standard user exit parameter list are:

Field | Offset | Length | Picture | Description
SXPLVER | X'00' | 4 | pointer | Address of a fullword containing the version number of this parameter list.
 | X'04' | 4 |  | Reserved (value = 0).
SXPLAWRK | X'08' | 4 | pointer | Address of a 512-byte work area for use by the exit routine. The address is different each time that this exit routine is called .
SXPLFSPL | X'0C' | 4 | pointer | Address of the NDM interface block.
 | X'10' | 8 |  | Reserved (value = 0).
Parent topic: IMS Support in Enterprise Server


JCL Commands

  • cassub
    Runs a JCL batch job.
  • casout
    Starts a batch service execution process or administers a batch job.
Parent topic: Reference for MSS Deployment


cassub

Runs a JCL batch job.

Syntax:

cassub [/res-name] or [/saddress] or [/les-name]
       [/jjobfile-name-by-content]
       [/xjobfile-name-by-reference]
       [/uuser-ID]
       [/ppassword]
       [/cgroup]
       [/vversion]

Parameters:

Options /r, /s, /l are alternative ways of identifying the enterprise server that you want to connect to.

/res-name
Name of the enterprise server to run the job. Defaults to ESDEMO
Note: When calling this utility from JCL or 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.
/saddress
Submit the job to a remote server. address is the address of the listener associated with the server's MF JES service. The format is protocol:ip-address:port, where:
  • protocol is tcp, or tcpssl if you are using an SSL-enabled listener
  • ip-address is either the text host name or IP address of the server listener
  • port is the port value
/les-name
Alternative to using the /r and /s options. Name of the enterprise server to run the job. You must specify a name - there is no default. This option searches all the repositories specified in mf-client.dat (or whichever configuration file you have identified with the MFC_CONFIG environment variable) for a server with the given name. Repositories are specified in the [directories] section, in the format:
mrpi://host[:port]

or:

file:///path-to-repository
/jjobfile-name-by-content
Path and filename of the file containing the JCL to run. See Comments below.
/xjobfile-name-by-reference
Path and filename of the file containing the JCL to run. See Comments below.
/u user-id
Authorization user ID. See Security below.
/p password
Authorization password. See Security below.
/cgroup
Authorization group (optional). See Security below.
/vversion
The version of the job control system software to use:
  1. VSE/Power
  2. JES2 (default)
  3. JES3

Dependencies

To use this command:

  • If you specify the /r parameter, you must have started the enterprise server named with the /r parameter first (or the ESDEMO on the local machine if you do not specify either /r or /s) using the casstart command. If you specify the /s parameter, you must have started the enterprise server identified by the /s parameter, using ES Admin.
  • You must be running under the same user ID as the enterprise server named with the /r parameter. 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.
  • In order to successfully run the cassub command, you must have execute permissions on the cassub resource within the OPERCMDS resource class

Comments

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

You must specify either the /j parameter or the /x parameter.

/r and /s are mutually exclusive. If you do not supply either, it is assumed that you are submitting to the server ESDEMO on the local machine.

For /x (by reference) the submitted file must be on the same platform as the enterprise server. This technique is more efficient, since only the name of the file is passed by the communications link. This is used internally (internal reader). You would use this technique where you run a job scheduling system on the same platform as the target enterprise server.

For /j (by content) the submitted file must be on the client's platform (which could be the same platform as the target enterprise server). The submitted JCL is physically passed over the communications link. This would be appropriate for an interactive user that has created the job stream on their machine and wants to submit it to an enterprise server running on another platform.

You can specify the /j or /x parameter more than once, in order to submit several JCL files in the same command.

The job is run by the most recently started available initiator that can handle the class specified on the JOB card.

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, please see casstart.

Security

If you are running this command against a secure region, then you will need to specify the /u and /p parameters, and optionally the /c parameter. If you omit these parameters, your job may fail with an authentication error.

Parent topic: JCL Commands


casout

Starts a batch service execution process or administers a batch job.

Syntax:

casout {/res-name|/sprototype:host:port|/lservername}
       [/uuserid]
       [/ppassword]
       [/cgroup]
       [/gnumber]
       [/gnumber:reldd]
       [/doutput-dsn]
       [/iclasses]
       [/jjobnumber:step[:procstep]]
       [/knumber]
       [/mnumber]
       [/fnumber]
       [/oStart]
       [/oStart:QM:Q[:listener-name]]
       [/oStop:listener-name]
       [/oDelete:listener-name]
       [/oList]
       [/oList:name]
       [/qmessage-classes]
       [/eIMScommand]
       [/wmpr-name]
       [/tprocess-ID]
       [/v]
       [/nprinter-name]
       [/boutput-classes]
       [/xprinter-exit]

Connection parameters

Important: You must include only one of the following connection options.
/res-name
Connect to the named enterprise server. Defaults to ESDEMO.
Restriction: When calling this utility from JCL or 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.
/sprototype:host:port
Use the specified URL to find the enterprise server to connect to, for example stcp:localhost:9003.
/lservername
Look up the specified server name to find the enterprise server to connect to.

Security parameters

Important: You must include these details when the specified enterprise server is secure.
/uuserid
Authorization user ID.
/ppassword
Authorization password.
/cgroup
The sign-on group to be used when running commands.

Categories

JCL parameters
/gnumber
/gnumber:reldd
Display all sysout for job number number, or retrieve the relative DD for job number number.
/doutput-dsn
Output DSN for sysout retrieval. The /d option must precede the /g option.
/iclasses
Start an initiator to run jobs of the named classes.
/jjobnumber:step:procstep
Restart the job at the specified step/procstep. The procstep is optional.
/knumber
Kill job number number.
/mnumber:class
Modify job number number to use the specified class.
/fnumber
Flush the output of job number number.
MQ listener parameters
/oStart
Enable MQ listener support.
/oStart:QM:Q[:listener-name]
Start the MQ listener defined for the specified queue manager QM and queue Q. If you want to start a specific listener, include the listener-name. Otherwise, Enterprise Server automatically creates and generates a name for the listener using the following form:
z#nnnnnn

where nnnnnn is a generated number set initially to 000001, and incremented by 1 with the creation of each subsequent listener.

/oStop:listener-name
Stop the named listener.
/oDelete:listener-name
Delete the named listener.
/oList
Display details of all defined MQ listeners and writers.
/oList:name
Display details for the named listener or writer.
IMS parameters
/qmessage-classes
Start an IMS Message Processing Region for the specified classes.
/eIMScommand
Execute the specified IMS command.
/wmpr-name
Name of the IMS MPR to be used.
Generic parameters
/tprocess-ID
Terminate the batch initiator, batch printer or IMS MPR that has the specified process ID.
/v
List all batch initiators, batch printers and IMS MPRs.
Printer parameters
/nprinter-name
Specifies the name of the physical device to be used by a new batch printer. This option is used with the /b and /x options.
/boutput-classes
Specifies the output classes to be handled by a new batch printer. This option is used with the /n and /x options.
/xprinter-exit
Specifies the name of the name of a printer exit to be associated with a new batch printer. Used with the /n and /b options.

Dependencies

  • You must have started the enterprise server before you can issue a casout command.
  • In order to successfully run the casout command, you must have execute permissions on the casout resource within the OPERCMDS resource class.

Comments

The /r, /s and /l options are alternatives and are mutually exclusive.

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

Examples

Starting an initiator for classes EFG on Enterprise Server JCLT:

casout /rJCLT /iEFG

Start a batch printer using the physical device "TestPrinter" for classes EFG on Enterprise Server JCLT:

casout /rJCLT /bEFG /n"TestPrinter"

Start a batch printer as in the previous example, but this time associate it with a printer exit (sampprnx):

casout /rJCLT /bEFG /n"TestPrinter" /xsampprnx

Start an IMS Message Processing Region for specified message classes:

casout /rJCLTT /q001

Start a listener connected to the Queue Manager named CSQ1 listening on the IMSMQ.OQ queue with a listener name of BANKBRDG on Enterprise Server BANKDEMO:

casout /rBANKDEMO /oStart:CSQ1:IMSMQ.OQ:BANKBRDG

Stop the BANKBRDG listener on Enterprise Server BANKDEMO:

casout /rBANKDEMO /oStop:BANKBRDG

show all the listeners/writers, as shown in ESMAC, including the above-created listener

Return codes

When running casout from a command line, get the return code by running the following command:

echo %ERRORLEVEL%
All functions
Code | Description
0 | Successful completion
Codes relating to job modification
Code | Description
5 | The job is actively processing, requeued
8 | The job is not in the Output Hold queue, or does not exist
8 | The job is in the Output Hold queue, requeued
8 | The job is not in the Input Hold queue or does not exist for Release command
16 | The job does not exist for Class command
99 | You have attempted to invoke a sub-command that is not yet implemented
Codes relating to flushing jobs
Code | Description
4 | Job flushed
16 | Job not flushed - see secondary error code returned in message
Codes relating to job output
Code | Description
< 9 | The job's log was retrieved
1 | Job is in the Input Hold Queue
2 | Job is being parsed for syntax
3 | Job is in the Input Queue
4 | Job is moving from Input Queue to "Actively processing"
5 | Job is being processed
7 | Job is complete and is on the Held Output Queue
8 | Job is in the Output Queue
16 | Invalid job number - you have attempted to retrieve sysout data for a non-existent job
16 | Invalid job number or DD for job, retrieval request ignored
Codes relating to restarting jobs
Code | Description
16 | The job does not exist for restart
32 | Restart processing is not turned on. You must set the ES_JES_RESTART environment variable in order to enable restart processing.
Codes relating to killing jobs
Code | Description
16 | The job is not active. Kill request ignored.
Codes relating to IMS command execution
Code | Description
15 | Commands must be preceded by a / (forward slash)
16 | IMS command failed, no response from TMC
Codes relating to process termination
Code | Description
8 | SEP is not an initiator, printer, or IMS MPR
Codes relating to JES and IMS functions
Code | Description
99 | JES/IMS support is not enabled for the region, request rejected
Codes relating to security
Code | Description
199 | User specified is either not authorized to work with JCL or their password is not correct. Provide valid credentials.
Codes relating to connectivity
Code | Description
15 | Cannot connect to region. This might be because the region is not started, or the IP address or port are wrong.
Parent topic: JCL Commands
Related information
Restarting Jobs


JCL Environment Variables

  • ES_JES_FREE_SSTM_SYSOUT
    Frees the memory assigned to store details about each CICS spool file that you create using the CICS Spool Write API's, once the spool file has been created.
  • 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_CHARSET
    Specifies which character set an enterprise server is to use.
  • MF_DUPJOBS
    Specifies whether jobs with duplicate names are allowed to run in parallel.
  • MF_FALLTHRUCHECK
    Specifies that MSS is to check that the main COBOL program ends by executing a GOBACK or STOP RUN.
  • MF_JCL_AUDIT
    Specifies that the audit log records audit information when a catalog entry is deleted.
  • MF_JESPWR_EXIT
    MF_JESPWR_EXIT is used to pass JES2 and VSE PWR statements to a user exit, MFJESPWR. If this environment variable is set the JCL execution engine will call the exit program, MFJESPWR, whenever a JES2 or VSE PWR statement is encountered. It passes the contents of the JCL record plus Job and Job Step information . A sample MFJESPWR.cbl is included with the product.
  • MF_NODD
    Specifies what action MSS is to take at run time if a job step uses a file that has not been allocated.
  • MF_SMS
    Turns on support for SMS data classes.
  • MF_UCC11
    Enables emulation of UCC11, the JCL job re-start functionality.
  • MF_USESCA7
    Specifies that MSS accepts CA7 Scheduler control statements as comments rather than diagnosing them as errors.
  • MFJSENGINE
    Specifies which sort engine the utility MFJSORT is to emulate.
  • MFREXX_CHARSET
    Specifies the character set used by the REXX engine when working with hexadecimal strings or performing string comparisons.
  • 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.
  • MFREXX_NOT
    Specifies one or more characters to be used for the NOT operator in addition to REXX's default, which is "¬".
  • MFREXX_OR
    Specifies one or more characters to be used for the OR operator in addition to REXX's default, which is "|".
  • MFREXX_CONCAT
    Specifies one or more characters to be used for the CONCAT operator in addition to REXX's default, which is "||".
  • MFUSERCAT_NODE
    Sets node to enable DATACLAS support.
Parent topic: Reference for MSS Deployment


ES_JES_FREE_SSTM_SYSOUT

Frees the memory assigned to store details about each CICS spool file that you create using the CICS Spool Write API's, once the spool file has been created.

This helps avoid problems with receiving 'out of memory' errors, when creating multiple new files.

Warning: Setting the variable also removes the tracking information about the file which means that the file's status (SPOOLED) no longer appears in the JESYSMSG for the SSTM job.

Syntax:

ES_JES_FREE_SSTM_SYSOUT=Y

Properties

The default value is N (not enabled).

Parent topic: JCL Environment Variables


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.
Note:

You can alias any program other than IEFBR14, which is always processed as IEFBR14.

Syntax:

MF_ALIAS=program-name1 alias1 [program-name2 alias2] ...[program-name10 alias10]

Comments:

An entry shorter than 8 characters must have trailing spaces extending its length to 8 characters.

Example:

MF_ALIAS=IKJEFT1BIDAEFT01MYPROG  THEIRPRG

adds:

Program-name | Alias
IKJEFT1B | IDAEFT01
MYPROG | THEIRPRG
Parent topic: JCL Environment Variables


MF_CHARSET

Specifies which character set an enterprise server is to use.

Syntax:

MF_CHARSET=A|E|ASCII|EBCDIC

Properties:

Default: ASCII

Comments:

A is an abbreviation for ASCII. E is an abbreviation for EBCDIC.

Parent topic: JCL Environment Variables


MF_DUPJOBS

Specifies whether jobs with duplicate names are allowed to run in parallel.

Syntax:

MF_DUPJOBS=Y|N

Properties:

Default: N
Parent topic: JCL Environment Variables


MF_FALLTHRUCHECK

Specifies that MSS is to check that the main COBOL program ends by executing a GOBACK or STOP RUN.

Syntax:

MF_FALLTHRUCHECK=y|n

Properties:

Default: y (Yes)

Comments:

If MF_FALLTHRUCHECK is set to Yes and the check fails, MSS issues this message:

JCLCM0213S Main pgm xxxxxxxx did not issue GOBACK or STOP RUN.
Parent topic: JCL Environment Variables


MF_JCL_AUDIT

Specifies that the audit log records audit information when a catalog entry is deleted.

Syntax:

MF_JCL_AUDIT=DELT|DELJ|DELT,DELJ

Parameters:

DELT | Logs audit information each time an ESMAC/CAS utility deletes a catalog entry
DELJ | Logs audit information each time a step in a JCL job deletes a catalog entry
DELT,DELJ | Logs audit information each time either an ESMAC/CAS utility or a JCL job step deletes a catalog entry

Properties:

Default: None

Comments:

The information recorded in the log is:
  • The user who deleted the catalog entry
  • The group to which the user belongs
  • Whether the catalog entry was deleted by an ESMAC user or a JCL job step
  • The name of the deleted catalog entry
  • Whether the standard delete operation or the JCL delete operation was performed

Example:

The following is a sample audit log entry:
2000/01/01 00:00:00.000 4232 MF 0 1 "SYSAD   SYSADM   000000ESMAC   POSYSAD   MVSCATIODLET"
Where:
SYSAD | The user ID
SYSADM | The group to which the user belongs
000000ESMAC | The entry was deleted by an ESMAC user
POSYSAD | The name of the deleted catalog entry
MVSCATIODLET | The standard delete operation (DLET) was used
Parent topic: JCL Environment Variables


MF_JESPWR_EXIT

MF_JESPWR_EXIT is used to pass JES2 and VSE PWR statements to a user exit, MFJESPWR. If this environment variable is set the JCL execution engine will call the exit program, MFJESPWR, whenever a JES2 or VSE PWR statement is encountered. It passes the contents of the JCL record plus Job and Job Step information . A sample MFJESPWR.cbl is included with the product.

Syntax:

MF_JESPWR_EXIT= Y

Properties:

The default value is OFF ( i.e. not set )

Parent topic: JCL Environment Variables


MF_NODD

Specifies what action MSS is to take at run time if a job step uses a file that has not been allocated.

Syntax:

MF_NODD=a|r

Parameters:

a | Abend the program
r | Return the file status 3/5

Properties:

Default: abend
Parent topic: JCL Environment Variables


MF_SMS

Turns on support for SMS data classes.

Syntax:

MF_SMS=ON|OFF

Properties:

Default: OFF

Comments:

SMS is IBM's Storage Management Subsystem. MSS provides emulation for SMS data classes only.

To enable DATACLAS support this variable needs to be set ON in addition to setting MFUSERCAT_NODE=SYSMFE1

Parent topic: JCL Environment Variables


MF_UCC11

Enables emulation of UCC11, the JCL job re-start functionality.
Note: This environment variable works independently of the JCL RESTART parameter.

Syntax:

MF_UCC11=y|n|m

Properties:

Y
JCL job re-start functionality is enabled. When restarting a job with DISP=(NEW,CATLG), it will not result in job failure due to the data set already being cataloged.
M

On restart, a catalogued data set is presumed to have an initial disposition of MOD rather than NEW. As a result, any new data is appended to the existing data set.

N
JCL job re-start functionality is disabled.
Default: N
Parent topic: JCL Environment Variables


MF_USESCA7

Specifies that MSS accepts CA7 Scheduler control statements as comments rather than diagnosing them as errors.

Syntax:

MF_USESCA7=ON|OFF

Properties:

Default: ON

Comments:

CA7 Scheduler control statements begin with # in column 1.

Parent topic: JCL Environment Variables


MFJSENGINE

Specifies which sort engine the utility MFJSORT is to emulate.

Syntax:

MFJSENGINE=DFSORT|SYNCSORT

Properties:

Default: DFSORT
Parent topic: JCL Environment Variables


MFREXX_CHARSET

Specifies the character set used by the REXX engine when working with hexadecimal strings or performing string comparisons.

Syntax:

MFREXX_CHARSET=charset

Parameters:

charset A value of E represents EBCDIC and a value of A represents ANSI.

Properties:

Default: "E"
Parent topic: JCL Environment Variables


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.

Syntax:

MFREXX_LSEQ_RECSIZE_MAX=rec-length

Parameters:

rec-length Record length to use. The minimum value you can specify is 255. Specifying an invalid value, or a value less than 255, results in the default value being used.

Properties:

Default: 255
Parent topic: JCL Environment Variables


MFREXX_NOT

Specifies one or more characters to be used for the NOT operator in addition to REXX's default, which is "¬".

Syntax:

MFREXX_NOT=character-specification

Parameters:

character-specification 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.

Properties:

Default: "¬"

Comments:

Any error in the specification of the additional characters, including the specification of alphabetic or numeric characters, results in the environment variable being ignored.

Parent topic: JCL Environment Variables


MFREXX_OR

Specifies one or more characters to be used for the OR operator in addition to REXX's default, which is "|".

Syntax:

MFREXX_OR=character-specification

Parameters:

character-specification 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.

Properties:

Default: "|"

Comments:

Any error in the specification of the additional characters, including the specification of alphabetic or numeric characters, results in the environment variable being ignored.

Parent topic: JCL Environment Variables


MFREXX_CONCAT

Specifies one or more characters to be used for the CONCAT operator in addition to REXX's default, which is "||".

Syntax:

MFREXX_CONCAT=character-specification

Parameters:

character-specification 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.

Properties:

Default: "||"

Comments:

Any error in the specification of the additional characters, including the specification of alphabetic or numeric characters, results in the environment variable being ignored.

Parent topic: JCL Environment Variables


MFUSERCAT_NODE

Sets node to enable DATACLAS support.

Syntax:

MFUSERCAT_NODE=SYSMFE1

Properties:

Default: No value assigned

Comments:

To enable DATACLAS support this variable needs to be set in addition to setting MF_SMS=ON.

Parent topic: JCL Environment Variables


TSO Support in Enterprise Server

Enterprise Server supports the use of TSO commands and REXX execs.

TSO commands can be run in a TSO batch (or background) session, using the IDAEFT01 (IKJEFF01) utility. TSO interactive processing is not supported in Enterprise Server.

Enterprise Server does not support CLIST processing.

  • TSO Commands and Micro Focus Extensions
    You can enter TSO commands and Micro Focus extensions individually within a REXX exec.
Parent topic: Reference for MSS Deployment


TSO Commands and Micro Focus Extensions

The TSO commands and Micro Focus extensions supported by Enterprise Server are listed below. Please refer to the IBM TSO documentation for any additional information about TSO commands.

Note: In addition to the TSO commands referenced below, the following IDCAMS commands may also be used in a batch TSO job. For information about the individual commands, please refer to the IBM IDCAMS documentation.
  • ALTER
  • DEFINE CLUSTER, DATA, INDEX, ALTERNATEINDEX, GDG, PATH, NONVSAM, CATALOG, ALIAS, USERCATALOG, PAGESPACE

    ALIAS, USERCATALOG and PAGESPACE will be parsed but not actioned.

  • REPRO
  • PRINT
  • VERIFY
  • BLDINDEX

    BLDINDEX is not required for indexed files with this Micro Focus file system and is provided for compatibility with the mainframe.

  • ALLOCATE
    Allocates an MVS data set to the current user and defines the data set's DD name.
  • ATTRIB
    Allows DCB parameters to be dynamically defined and named for use in subsequent ALLOCATE commands.
  • CALL
    Invokes a program.
  • DELETE
    Deletes an MVS data set and its related PC file.
  • DSN
    Invokes the DSN command processor used to run DB2 programs.
  • EXEC
    Executes a TSO command, CLIST or REXX exec.
  • FREE
    Frees allocation of a data set.
  • LISTALC
    Displays the list of currently allocated DD names.
  • LISTCAT
    Lists the entries in the catalog with the high-level data set qualifier equal to the user ID defined to Enterprise Server.
  • LOGOFF
    Terminates the current TSO session.
  • PROFILE
    Allows you to specify different PREFIX and PROMPT settings.
  • RELATE
    A Micro Focus extension that relates an MVS data set name in the catalog to a PC file name.
  • REXX
    Executes a file containing a set of JCL statements.
  • SUBMIT
    Executes a file containing a set of JCL statements.
  • TIME
    Displays the current time and date and the CPU seconds used.
Parent topic: TSO Support in Enterprise Server


ALLOCATE

Allocates an MVS data set to the current user and defines the data set's DD name.

The following example allocates the existing data set TESTDATA.SORTED.DATA, with the DD name SYSUT1.

ALLOCATE FILE(SYSUT1) DATASET(TESTDATA.SORTED.DATA) OLD

Operands Support

The following operands are supported for ALLOCATE:

BLKSIZE | DUMMY | SHR
BLOCK | FILE | SPACE
CYLINDERS | LIKE | SYSOUT
DATACLAS | LRECL | TRACKS
DATASET | MOD | TRTCH
DDNAME | NEW | USING
DIR | OLD | WRITER
DSNAME | RECFM |
DSORG | REUSE |

The following are parsed and ignored:

ACCODE | DEN | NOBURST
ALTFILE | DEST | OPTCD
ATTRLIST | EROPT | OUTPUT
BFALN | EXPDT | PARALLEL
BFTEK | FCB | POSITION
BUFL | FLASH | RELEASE
BUFNO | FORMS | RETPD
BUFOFF | INPUT | ROUND
BURST | KEEP | UCS
CATALOG | KEYLEN | UNCATALOG
CHARS | LABEL | UNIT
COPIES | LIMCT | VOLUME
DELETE | NCP | VSEQ
Parent topic: TSO Commands and Micro Focus Extensions


ATTRIB

Allows DCB parameters to be dynamically defined and named for use in subsequent ALLOCATE commands.

The following example sets up an attribute called DATA1 that can be used in conjunction with an ALLOCATE command to provide DCB information for a DD name.

ATTRIB DATA1 BLKSIZE(32720) LRECL(80) DSORG(PS) RECFM(FB)

Operands Support

The following operands are supported for ATTRIB:

BLKSIZE | LRECL | TRTCH
DSORG | RECFM |

These operands produce identical output for SQL and VSAM datasets.

The following are parsed and ignored:

BFALN | BUFOFF | KEYLEN
BFTEK | DEN | NCP
BUFL | ERROPT | OPTCD
BUFNO | EXPDT | RETPD
Parent topic: TSO Commands and Micro Focus Extensions


CALL

Invokes a program.

The following example invokes program PROG1.

CALL PROG1

Operands Support

The following operands are supported for CALL:

ASIS | NOENVB | PASSENVB
CAPS | PARM | PROGRAM
Parent topic: TSO Commands and Micro Focus Extensions


DELETE

Deletes an MVS data set and its related PC file.

The following example deletes the data set TESTDATA.UNSORTED.DATA.

DELETE 'TESTDATA.UNSORTED.DATA'

Operands Support

The following operands are supported for DELETE:

DATASET | DSNAME
DDNAME | FILE

The following are parsed and ignored:

ALIAS | NONVSAM | PRG
CATALOG | NOPURGE | PURGE
CLUSTER | NOSCRATCH | SCRATCH
ERASE | NPRG | SPACE
GDG | NSCR | SPC
GENERATIONDATAGROUP | NVSAM | UCAT
NERASE | PAGESPACE | USERCATALOG
NOERASE | PGSPC |
Parent topic: TSO Commands and Micro Focus Extensions


DSN

Invokes the DSN command processor used to run DB2 programs.
In Enterprise Server, the subcommands ABEND, BIND, DCLGEN, FREE, REBIND, SPUFI, SYSTEM, RETRY, TEST and PLAN are passed to the database sub system which may or may not support them.

The following example invokes the DSN subcommand processor to execute the RUN subcommand, which invokes the program PROG1 with the parameter string "HELLO". The END subcommand terminates the DSN subcommand processor.

DSN
RUN PROGRAM(PROG1) PLAN(PLANX) PARMS('HELLO')
END

Refer to the IBM DB2 for z/OS documentation for any additional information about the DSN command.

Operands Support

The following operands are supported for DSN:

RUN SYSTEM

The following are parsed and ignored:

RETRY TEST

The following are passed to the database sub system which may or may not support them:

ABEND | DCLGEN | FREE
BIND | END | REBIND
DATA | ENDDATA | SPUFI
Parent topic: TSO Commands and Micro Focus Extensions


EXEC

Executes a TSO command, CLIST or REXX exec.

The following example executes the member ABCD from the partitioned data set MYPDS.CLIST.

EXEC 'MYPDS.CLIST(ABCD)'
Parent topic: TSO Commands and Micro Focus Extensions


FREE

Frees allocation of a data set.
The following example frees the allocation for the data set with DD name SYSUT1.
FREE FILE(SYSUT1)

Operands Support

The following operands are supported for FREE:

ALL | DDNAME | DSNAME
DATASET | DELETE | FILE
Parent topic: TSO Commands and Micro Focus Extensions


LISTALC

Displays the list of currently allocated DD names.

Operands Support

The following operands are supported for LISTALC:

HISTORY | STATUS
MEMBERS | SYSNAMES

Specifying MEMBERS for a PDS also lists the PDS member names.

Parent topic: TSO Commands and Micro Focus Extensions


LISTCAT

Lists the entries in the catalog with the high-level data set qualifier equal to the user ID defined to Enterprise Server.

Operands Support

If you invoke this command with the Micro Focus extension /F, it displays additional information.

The following operands are supported for LISTCAT:

ALL | /F | LVL
ENTRIES | LEVEL |

The following are parsed and ignored:

DATA | OFILE | USERCATALOG
INDEX | OUTFILE |
NONVSAM | SPACE |
Parent topic: TSO Commands and Micro Focus Extensions


LOGOFF

Terminates the current TSO session.
Once LOGOFF executes, remaining commands in the input stream are ignored.
Parent topic: TSO Commands and Micro Focus Extensions


PROFILE

Allows you to specify different PREFIX and PROMPT settings.

The following example adds a data set prefix of TVDF to any data set name not enclosed in quotes, and turns off prompting for REXX execs during the active TSO session.

PROFILE PREFIX(TVDF) NOPROMPT
Parent topic: TSO Commands and Micro Focus Extensions


RELATE

RELATE can be used in conjunction with an ALLOCATE command to set up tests in a TSO session.

The following example relates the MVS data set TESTDATA.SORTED.DATA to the PC file C:\MYFILE.DAT.

RELATE TESTDATA.SORTED.DATA C:\MYFILE.DAT

Operands Support

The following operands are supported for RELATE:

dataset name pc file name
Parent topic: TSO Commands and Micro Focus Extensions


REXX

Executes a file containing a set of JCL statements.

The following example executes the REXX statements contained in the PDS member IOCBL02.

REXX 'TEST.SYSEXEC(SBCS4315)'

Operands Support

The following operands are supported for REXX:

rexx name
Parent topic: TSO Commands and Micro Focus Extensions


SUBMIT

Executes a file containing a set of JCL statements.

The following example executes the JCL statements contained in IOCBL02.

SUBMIT 'TVDF.WORK.CNTL(IOCBL02)'

Operands Support

The following operands are supported for SUBMIT:

dataset name
Enter an example to illustrate your reference here (optional).
Parent topic: TSO Commands and Micro Focus Extensions


TIME

Displays the current time and date and the CPU seconds used.
The CPU seconds returned using the TIME command represent cumulative CPU time from LOGON. Current time and date are local.
Parent topic: TSO Commands and Micro Focus Extensions


MSS Error Messages

See your locally installed Help for the messages that Enterprise Server can display when it is running with MSS enabled. It gives an explanation or advice or both for those errors that are not self-explanatory.

  • JCL Error Messages
Parent topic: Reference for MSS Deployment


JCL Error Messages

  • JCLAM Error Messages
  • JCLCM Error Messages
  • JCLGN Error Messages
  • JCLIM Error Messages
  • JCLPT Error Messages
  • JCLUT Error Messages
  • JCLZZ9999S job-number job-name MESSAGE UNDEFINED MESSAGECODE
  • SORT - MFJSORT Error Messages
  • MFJSORT Summary Messages
  • JES Messages
Parent topic: MSS Error Messages


JCLAM Error Messages

Select the number of the message you require details about.

  • JCLAM0000 - JCLAM0119
  • JCLAM0120 - JCLAM0139
  • JCLAM0140 - JCLAM 0159
  • JCLAM0160 - JCLAM0179
  • JCLAM0180 - JCLAM0230
  • JCLAM0231 -
Parent topic: JCL Error Messages


JCLCM Error Messages

Select the number of the message you require details about:

  • JCLCM0000 - JCLCM0199
  • JCLCM0200 - JCLCM0299
  • JCLCM0400 - JCLCM0499
  • JCLCM0500 - JCLCM0599
  • JCLCM0600 - JCLCM0699
  • JCLCM0800 - JCLCM0899
  • JCLCM0900 - JCLCM0999
  • JCLCM1000 - JCLCM2000
Parent topic: JCL Error Messages


JCLCM0000 - JCLCM0199

  • JCLCM0000I job-number job-name JCL PROCESSOR TERMINATED
    The JCL processor has terminated. This does not imply an error. It could occur, for example, if a debugging session is cancelled while a jobstream is being processed.
  • JCLCM0001U job-number job-name I/O ERROR ON SYSTEM CATALOG FILE
    Configuration error.
  • JCLCM0010W SYSOUT Limit limit exceeded by DD name
  • JCLCM0011I OUTLIM limit for DD name incremented by amount by user exit MFJUSOXT
  • JCLCM0012S Job cancelled by user exit MFJUSOXT
  • JCLCM0013S Job cancelled by global OUTLIM setting of setting
  • JCLCM0094I Non-JCL record in the input stream has caused this SYSIN DD statement to be generated.
    This message, while it never appears in any JCL listings, is referred to in the generated SYSIN DD statement. It means that in your JCL source stream, you have one or more non-JCL records before the final // if any.
  • JCLCM0121S Unexpected return type from RJSECA-FC-Execute %1$s.
  • JCLCM0122S Incorrect password caused SAF failure on the host.
  • JCLCM0123S Expired password caused SAF failure on the host.
  • JCLCM0124S Invalid user id caused SAF failure on the host.
  • JCLCM0125E %1$s is not supported.
  • JCLCM0126E %1$s is not yet supported.
  • JCLCM0127S Host dataset %1$s unexpectedly created by alien job.
  • JCLCM0128S Host dataset %1$s unexpectedly deleted by alien job.
    Explains purpose of topic. Written as sentence fragment. Contains no more than two sentences.
  • JCLCM0129W LRECL of host RECFM F dataset %1$s assumed to be 80.
  • JCLCM0130W LRECL of host RECFM V dataset %1$s assumed to be 255.
  • JCLCM0147U job-number job-name NO DATASET NAME SPECIFIED
    The function requested requires a data set name to be specified.
  • JCLCM0158U job-number job-name MVS data set "name" not found
    The specified MVS data set is not in the catalog.
  • JCLCM0159U job-number job-name FILE OPEN ERROR FILENAME
    There was an open error on the main source file submitted to the JCL scanner for processing.
  • JCLCM0160U job-number job-name FILE I/O ERROR FILENAME
    There was an I/O error on the main source file submitted to the JCL scanner for processing.
  • JCLCM0161U job-number job-name DATASET TYPE INVALID DATASETNAME
    The specified data set is of a type that cannot be used for the requested function.
  • JCLCM0162U job-number job-name FILE IS EMPTY FILENAME
    The specified file is empty. The function you have attempted cannot be performed on an empty data set or file.
  • JCLCM0163U job-number job-name MVSJOBNO ERROR ASSIGNING JOBNUM
    An internal error has been detected while attempting to assign a job number. The return-code from MVSJOBNO.DLL is non-zero.
  • JCLCM0164A job-number job-name All job numbers in the range lower-job-number:upper-job-number are in use.
    The system has used up all available job numbers and cannot process this job.
  • JCLCM0165S Open for joblog "filename" failed. Also see JCLCM0166
    Use the extended file status code for more information on this failure.
  • JCLCM0166S File status code for last file I/O failure was value
    Use the extended file status code for more information on this failure.
  • JCLCM0169I JCL copied
  • JCLCM0170I job-number job-name JCL SCANNED - NO ERRORS
    The job submitted contains no syntax errors.
  • JCLCM0171E job-number job-name JCL SCANNED - JCL ERROR
    The job submitted contains syntax errors which are detailed in other messages.
  • JCLCM0172E job-number job-name JOB FAILED - JCL ERROR
    The job submitted contains a JCL syntax error.
  • JCLCM0173I job-number job-name MFJUSCAN SCANNER EXIT - NO ERRORS
    The JCL scanner user exit module MFJUSCAN was called and ended with a zero return code.
  • JCLCM0174E job-number job-name MFJUSCAN SCANNER EXIT - JCL ERROR
    The JCL scanner user exit module MFJUSCAN was called and ended with a non-zero return code.
  • JCLCM0175S job-number job-name MFJUSCAN SCANNER EXIT - I/O ERROR ON FILENAME
    An I/O error has occurred while attempting to process the user error file returned to the JCL scanner.
  • JCLCM0180I job-number job-name Job ready for execution.
    The job named is ready for execution.
  • JCLCM0181S job-number job-name JOB ABENDED - ERRORCODE
    The job has ended abnormally with the specified return code.
  • JCLCM0182I job-number job-name JOB ENDED - RC(RETURNCODE)
    The job has ended normally with the specified return code.
  • JCLCM0185U job-number job-name Job flushed upon User Exit request.
    The user exit has requested that the job be flushed.
  • JCLCM0187I job-number job-name JOB SUBMITTED JOBNAME
    The specified job contains a valid job name, a job number has been assigned, and syntax checking of the JCL has started.
  • JCLCM0188I job-number job-name JOB STARTED.
    Execution of the submitted job has started.
  • JCLCM0189I job-number job-name STEP BYPASSED STEPNAME.PROCSTEPNAME
    Execution of the specified job step has been bypassed due to a prior abend or because of return codes.
  • JCLCM0190I job-number job-name STEP STARTED STEPNAME.PROCSTEPNAME
    Execution of the specified job step has started.
  • JCLCM0191I job-number job-name STEP ENDED STEP1 - COND CODE CONDITION-CODE
    Execution of the job step has completed normally with the specified return code.
  • JCLCM0192S job-number job-name STEP ABENDED STEP01 - COND CODE ABEND-CODE
    Execution of the job step has completed abnormally with the specified user abend, system abend, or run time error.
  • JCLCM0193U job-number job-name PROGRAM NOT FOUND - PROGRAMNAME
    The specified program cannot be located.
  • JCLCM0194S job-number job-name DCB MODEL NOT FOUND - DDNAME
    The specified DD statement references a DCB model data set which cannot be located.
  • JCLCM0195S job-number job-name DATASET IS NOT A GDG - DDNAME
    The specified DD statement refers to a GDG data set with a bias (+1) or (-1), but no GDG model by the same name exists in the catalog.
  • JCLCM0196S Resource allocation failed for dd-name<[concat dd seq no]>. Reason=nnn
    This is usually preceded by another JCLCM message providing additional information.
  • JCLCM0197S job-number job-name DISP=MOD, DSN INCOMPATIBLE - DDNAME
    The specified DD statement specifies DISP=MOD, which is incompatible with the organization of the data set name specified.
  • JCLCM0198I VSE CONFIG FILE - outcome : config-file
    Tells you the outcome of your attempt to load an optional VSE JCL configuration file (specified by the VSE_STARTUP_CFG environment variable).
  • JCLCM0199I job-number job-name Program program-name is cobol-dialectchar-setbyte-orderamode-type
    The program program-name, which is being executed, has the stated characteristics.
Parent topic: JCLCM Error Messages


JCLCM0200 - JCLCM0299

  • JCLCM0200S job-number job-name DISP=NEW, DATASET EXISTS - DDNAME
    The specified DD statement specifies DISP=NEW but the data set name specified already exists in the catalog.
  • JCLCM0201S job-number job-name DATASET IS NOT A PDS - DDNAME
    The specified DD statement refers to a PDS member but no PDS model by the same name exists in the catalog.
  • JCLCM0202S job-number job-name DISP=OLD/SHR, DATASET NOT FOUND - DDNAME
    The specified DD statement specifies DISP=OLD or DISP=SHR but the data set name specified does not exist in the catalog.
  • JCLCM0203S ACI option has overridden step abend S422
    You have requested the Automatic Catalog Input option, and therefore an S422 abend has been ignored.
  • JCLCM0205I job-number job-namePROGRAM FUNC=func/functext RC=rcode/rcodetext
    The specified program has detected an unexpected return code from the MVS Job Step Resource Manager (MJRM). Details of the function and return code are provided in the message.
  • JCLCM0206I job-number job-name ALLOCATION DEFERRED UNTIL OPEN - DDNAME
    In the specified DD statement, the first (or only) data set specified does not exist and the step being executed is an IMS batch step.
  • JCLCM0207I job-number job-name DUPLICATE DD STATEMENT IGNORED - DDNAME
    The specified DD statement is a duplicate of a DD statement defined earlier in the job step.
  • JCLCM0208I job-number job-name Host OS may require SPACE for DD "DD-name"
    The host operating system (MVS, OS/390, z/OS) might require that you specify the SPACE parameter unless the data set is allocated to a device such a tape device.
  • JCLCM0209S job-number job-name DISP=NEW, UNCATALOGED DUPLICATE EXISTS - DDNAME
    The specified DD statement specifies DISP=NEW but the data set name specified already exists in the catalog (in an uncataloged state).
  • JCLCM0210U job-number job-name I/O ERROR ON SPOOL FILE
    An I/O error has occurred while accessing the spool file containing JOB output.
  • JCLCM0211S job-number job-name Dataclass "name" does not exist
    This specified data class has not been defined to this system.
  • JCLCM0212S job-number job-name REFDD dataclass "name" does not exist
    This specified data class has not been defined to this system.
  • JCLCM0213S job-number job-name Main pgm name did not issue GOBACK or STOP RUN
    The specified main COBOL program fell through to the end of the program without executing a GOBACK or a STOP RUN statement.
  • JCLCM0214S Required resources could not be obtained
    All the required datasets for this job are unavailable. Probably some other job or user is using them.
  • JCLCM0216S Insufficient storage available to process the job
    Either you have defined more data sets than the system can handle, or there is an internal error.
  • JCLCM0217S Internal system error "internal code"
    Internal error.
  • JCLCM0218S System error "internal code"
    System error.
Parent topic: JCLCM Error Messages


JCLCM0400 - JCLCM0499

  • JCLCM0401U job-number job-name MISSING JOB STATEMENT
    JCL error. A JOB statement is required in the jobstream.
  • JCLCM0402E job-number job-name MISSING EXECUTE STATEMENT
    JCL error. At least one EXEC statement is required in the jobstream.
  • JCLCM0403E job-number job-name TOO MANY PROCEDURES REFERENCED
    JCL error. The job submitted has exceeded the maximum number of cataloged procedures that this system can load.
  • JCLCM0404E job-number job-name MISSING PEND STATEMENT
    JCL error. A PEND statement is required to end the instream procedure begun by a previous PROC statement.
  • JCLCM0405E job-number job-name RECURSIVE, ILLEGAL NESTING, OR LIMIT EXCEEDED
    JCL error. A procedure has attempted to execute another procedure. Nested procedures are not permitted.
  • JCLCM0406E job-number job-name PROCEDURE NOT FOUND
    JCL error. The procedure name specified cannot be located.
  • JCLCM0407E job-number job-name INVALID LABEL
    JCL error. The label on a JCL statement is invalid - for example, it exceeds eight characters.
  • JCLCM0408I UNKNOWN OUTPUT STMT OPERAND IGNORED
    You have used an unknown keyword.
  • JCLCM0409E job-number job-name INVALID OPERATOR
    JCL error. The JCL operator (EXEC, DD, etc.) contained on the statement is unknown.
  • JCLCM0410E job-number job-name INVALID CONTINUATION
    JCL error. The JCL statement contains an invalid continuation or the expected continuation was not received.
  • JCLCM0411E job-number job-name OPERAND TOO LONG
    JCL error. The JCL operand exceeds the length allowed for the JCL parameter.
  • JCLCM0412E job-number job-name NON-NUMERIC DATA DETECTED
    JCL error. Non-numeric data has been found in an operand that is required to be numeric.
  • JCLCM0413E job-number job-name DUPLICATE JOB
    JCL error. More than one JOB statement has been detected.
  • JCLCM0414E job-number job-name INVALID OR UNKNOWN OR UNEXPECTED OPERAND
    JCL error. The operand received is not recognized.
  • JCLCM0415E job-number job-name INVALID ADDRSPC OPERAND
    JCL error. The ADDRSPC operand is improperly coded.
  • JCLCM0416I job-number job-name INVALID JOBCLASS OPERAND IGNORED
    JCL error. The JOBCLASS operand is improperly coded and has been ignored.
  • JCLCM0417I job-number job-name INVALID MSGCLASS OPERAND IGNORED
    JCL error. The MSGCLASS operand on the JOB statement is improperly coded and has been ignored.
  • JCLCM0418E job-number job-name INVALID MSGLEVEL OPERAND
    JCL error. The MSGLEVEL operand is improperly coded.
  • JCLCM0419E job-number job-name INVALID PERFORM OPERAND
    JCL error. The PERFORM operand is improperly coded.
  • JCLCM0420E job-number job-name INVALID PRTY OPERAND
    JCL error. The PRTY operand is improperly coded.
  • JCLCM0421E job-number job-name INVALID RD OPERAND
    JCL error. The RD operand is improperly coded.
  • JCLCM0422I job-number job-name INVALID REGION OPERAND IGNORED
    JCL error. The REGION operand on the JOB or EXEC statement is improperly coded and has been ignored.
  • JCLCM0423E job-number job-name INVALID STEP NAME
    JCL error. The job step name is invalid.
  • JCLCM0424E job-number job-name INVALID PROCSTEP NAME
    JCL error. The procedure step name is invalid.
  • JCLCM0425E job-number job-name INVALID TIME OPERAND
    JCL error. The TIME operand is improperly coded.
  • JCLCM0426E job-number job-name INVALID TYPRUN OPERAND
    JCL error. The TYPRUN operand is improperly coded.
  • JCLCM0427E job-number job-name CONDITION STATEMENT IMPROPERLY FORMED
    JCL error. The COND operand is improperly coded.
  • JCLCM0428E job-number job-name INVALID CONDITION CODE
    JCL error. The condition code is improperly coded.
  • JCLCM0429E job-number job-name INVALID CONDITION OPERATOR
    JCL error. The condition operator is improperly coded.
  • JCLCM0430E job-number job-name INVALID PROGRAM NAME
    The program name is improperly coded.
  • JCLCM0431E job-number job-name INVALID DYNAMNBR OPERAND
    JCL error. The DYNAMNBR operand is improperly coded.
  • JCLCM0432E job-number job-name INVALID BURST OPERAND
    JCL error. The BURST operand is improperly coded.
  • JCLCM0433E job-number job-name INVALID CHKPT OPERAND
    JCL error. The CHKPT operand is improperly coded.
  • JCLCM0434E job-number job-name INVALID RECFM OPERAND
    JCL error. The RECFM operand is improperly coded.
  • JCLCM0435E job-number job-name INVALID LRECL OPERAND
    JCL error. The LRECL operand is improperly coded.
  • JCLCM0436E job-number job-name INVALID DISP OPERAND
    JCL error. The DISP operand is improperly coded.
  • JCLCM0437E job-number job-name UNEXPECTED STATEMENT
    JCL error. The JCL statement received was not expected.
  • JCLCM0438E job-number job-name PROCSTEP NOT FOUND
    JCL error. The procedure step name referenced cannot be located.
  • JCLCM0439E job-number job-name INVALID LABEL REFERENCE
    JCL error. The label reference on a JCL statement is invalid.
  • JCLCM0440E job-number job-name SYMBOL NOT FOUND
    JCL error. The symbolic parameter cannot be found on the PROC or EXEC statement.
  • JCLCM0441E job-number job-name UNKNOWN PROCSTEP NAME
    JCL error. The procedure step name referenced has not been defined by a previous EXEC statement.
  • JCLCM0442E job-number job-name INVALID OVERRIDE
    JCL error. The override is invalid.
  • JCLCM0443E job-number job-name INVALID POSITIONAL OPERAND
    JCL error. The positional operand was not expected.
  • JCLCM0444E job-number job-name INVALID DATASET NAME
    JCL error. The data set name is invalid.
  • JCLCM0445E job-number job-name INVALID REFER BACK
    JCL error. The refer back is invalid.
  • JCLCM0446E job-number job-name DCBMODEL NAME NOT FOUND
    JCL error. The model name specified in the DCB parameter cannot be found in the catalog.
  • JCLCM0447E job-number job-name INVALID DDNAME
    JCL error. The DD name is invalid.
  • JCLCM0448E job-number job-name INVALID DDNAME REFERENCE
    JCL error. The DD name deferral is invalid.
  • JCLCM0449E job-number job-name MISMATCHED PARENTHESES
    JCL error. An expected parenthesis was not received.
  • JCLCM0450E job-number job-name REFERENCED DD DOES NOT REFER TO A PDS MEMBER
    A reference such as PGM=*.step.pste.ddname refers to a DD name that does not reference a PDS member.
  • JCLCM0453E job-number job-name UNKNOWN RESTART STEP NAME
    JCL error. The step name specified in the RESTART operand of the JOB statement cannot be resolved.
  • JCLCM0454E job-number job-name INVALID ABEND CODE
    JCL error. The abend code in an IF statement or in the COND operand of the JOB or EXEC statement is specified incorrectly.
  • JCLCM0455E job-number job-name INVALID BLKSIZE OPERAND
    JCL error. The BLKSIZE operand is improperly coded.
  • JCLCM0456I job-number job-name BLKSIZE NOT A MULTIPLE OF LRECL
    JCL error. BLKSIZE must be a multiple of LRECL when both are coded and when RECFM=fixed is specified or implied.
  • JCLCM0457E job-number job-name INVALID EXPDT VALUE
    JCL error. The value specified for EXPDT is improperly coded or is not within the acceptable range.
  • JCLCM0458W job-number job-name INVALID FREE VALUE – DEFAULT OF (END) SUBSTITUTED
    JCL error. The value specified for FREE is improperly coded or is not within the acceptable range.
  • JCLCM0459E job-number job-name INVALID UCS VALUE
    JCL error. The value specified for UCS is improperly coded or is not within the acceptable range.
  • JCLCM0460E job-number job-name INVALID RECORG VALUE
    JCL error. The value specified for RECORG must be KS, ES, or RR.
  • JCLCM0461E job-number job-name INVALID DLM VALUE
    JCL error. The value specified for DLM is improperly coded.
  • JCLCM0462E job-number job-name INVALID AVGREC VALUE
    JCL error. The value specified for AVGREC is improperly coded or is not within the acceptable range.
  • JCLCM0463E job-number job-name TOO MANY LIBRARIES SPECIFIED
    JCL error. More than 15 libraries were specified on the JCLLIB statement.
  • JCLCM0464E job-number job-name INCLUDE NOT FOUND
    JCL error. The data set specified in the INCLUDE statement was not found.
  • JCLCM0465E job-number job-name DUPLICATE INSTREAM PROCEDURE
    JCL error. The instream procedure name is a duplicate of one already used.
  • JCLCM0466U job-number job-name INVALID JOBNAME
    JCL error. The job name specified is invalid.
  • JCLCM0467E job-number job-name CONFLICTING OR INCOMPATIBLE OPERANDS
    JCL error. Conflicting operands have been included on the JCL statement.
  • JCLCM0468E job-number job-name INVALID DSORG VALUE
    JCL error. The value specified for DSORG is improperly coded.
  • JCLCM0469I job-number job-name NONUNIQUE REFERENCE RESOLVED TO FIRST OCCURRENCE
    JCL error. This message indicates that there are multiple job steps with the same name as the referenced stepname.
  • JCLCM0470I job-number job-name NONUNIQUE REFERENCE RESOLVED TO CURRENT OCCURRENCE
    JCL error. This message indicates that there are multiple job steps with the same name as the referenced stepname.
  • JCLCM0471E job-number job-name OPERAND TABLE LIMIT EXCEEDED
    JCL error. The limit on the number of operands supported has been exceeded.
  • JCLCM0472E job-number job-name SYMBOL TABLE LIMIT EXCEEDED
    JCL error. The limit on the number of symbols supported has been exceeded.
  • JCLCM0473E job-number job-name INVALID NULL OPERAND VALUE
    JCL error. A keyword operand with no value was specified, but a value is required.
  • JCLCM0474E job-number job-name INVALID SYSOUT CLASS OPERAND
    JCL error. The SYSOUT class operand on the DD statement is improperly coded.
  • JCLCM0475I DD CHANGED TO DUMMY (DDNAME= MISSING)
    You have referenced a file for which there is no DDNAME statement.
  • JCLCM0476E job-number job-name Symbol "name" was not used
    The specified symbol is not used anywhere in the procedure. One explanation is that the symbol is misspelled.
  • JCLCM0477S More than 255 EXEC statements
  • JCLCM0486E Duplicate comma in action section of limitation type global SYSOUT limit
  • JCLCM0487E Global output limit number for limitation type too long
  • JCLCM0488E Closing bracket before action in limitation type global SYSOUT limit
  • JCLCM0489E No value decoded for limitation type global output limit
  • JCLCM0490E Error parsing numeric value for limitation type global SYSOUT limit
  • JCLCM0491E Invalid action parameter for limitation type global SYSOUT limit
  • JCLCM0499S job-number job-name FILE I/O ERROR OR FILE IS EMPTY
    There was an I/O error trying to read the referenced cataloged procedure or JCL included file, or the file is empty.
Parent topic: JCLCM Error Messages


JCLCM0500 - JCLCM0599

  • JCLCM0500E SPACE parameter "value" is invalid or misplaced
  • JCLCM0501E UNIT parameter "value" is invalid or misplaced
  • JCLCM0502E VOLUME parameter "value" is invalid or misplaced
  • JCLCM0503E Invalid USER parameter
  • JCLCM0504E TYPEXEC parameter "value" is invalid
  • JCLCM0505E DSNTYPE parameter "value" is invalid
  • JCLCM0506E account parameter or its length in error
  • JCLCM0507E programmer parameter or its length in error
  • JCLCM0508E Invalid ACCODE parameter
  • JCLCM0509E Invalid CCSID parameter
  • JCLCM0510E Invalid BYTES parameter
  • JCLCM0511E Invalid CARDS parameter
  • JCLCM0512E Invalid GROUP parameter
  • JCLCM0513E Invalid LINES parameter
  • JCLCM0514E Invalid NOTIFY parameter
  • JCLCM0515E Invalid PAGES parameter
  • JCLCM0516E Invalid PASSWORD parameter
  • JCLCM0517E PARM parameter or its length in error
  • JCLCM0518E Invalid RESTART parameter
  • JCLCM0519E Invalid SECLABEL parameter
  • JCLCM0520E Invalid UPLOAD parameter
  • JCLCM0521E Invalid DOWNLOAD parameter
  • JCLCM0522E Invalid MEMBER parameter
  • JCLCM0523E Invalid PCDSN parameter
  • JCLCM0524E COPIES parameter "value" has invalid value or syntax
  • JCLCM0525E Excess COPIES specification "value" rejected
  • JCLCM0526E FCB parameter "value" has invalid value
  • JCLCM0527E FLASH parameter "value" has invalid value
  • JCLCM0528E HOLD parameter "value" has invalid value
  • JCLCM0529E PRTSP parameter "value" has invalid value
  • JCLCM0530E SPIN parameter "value" has invalid value
  • JCLCM0531E TRTCH parameter "value" is invalid
  • JCLCM0532E "value" parameter is invalid
  • JCLCM0533E "value" parameter has invalid value
  • JCLCM0599I Excess VOLUME specification "value" ignored
Parent topic: JCLCM Error Messages


JCLCM0600 - JCLCM0699

  • JCLCM0600E - PORTNO "nn" parameter has invalid value
  • JCLCM0601E - PRMODE "nn" parameter has invalid value
  • JCLCM0602E - PRTERROR "nn" parameter has invalid value
  • JCLCM0603E - PRTOPTNS "nn" parameter has invalid value
  • JCLCM0604E - PRTQUEUE "nn" parameter has invalid value
  • JCLCM0605E - PRTY "nn" parameter has invalid value
  • JCLCM0606E - RESFMT "nn" parameter has invalid value
  • JCLCM0607E - RETAINS/RETAINF "nn" parameter has invalid value
  • JCLCM0608E - RETRYL/RETRYT "nn" parameter has invalid value
  • JCLCM0609E - ROOM "nn" parameter has invalid value
  • JCLCM0610E - SYSAREA "nn" parameter has invalid value
  • JCLCM0611E - THRESHLD "nn" parameter has invalid value
  • JCLCM0612E - TITLE "nn" parameter has invalid value
  • JCLCM0613E - TRC "nn" parameter has invalid value
  • JCLCM0614E - UCS "nn" parameter has invalid value
  • JCLCM0615E - USERDATA "nn" parameter has invalid value
  • JCLCM0616E - USERLIB "nn" parameter has invalid value
  • JCLCM0617E - WRITER "nn" parameter has invalid value
  • JCLCM0618E - Excess operand(s) starting with "nn" are ignored
  • JCLCM0619E - LSEQRECF parameter "nn" is invalid
  • JCLCM0620E - RESTART parameter "nn" is invalid
  • JCLCM0621E - HOSTJOB parameter "nn" is invalid
  • JCLCM0622U - System error writing nn file. Contact Micro Focus
  • JCLCM0623E - SUBSYS parameter "nn" is longer than 2698 bytes
  • JCLCM0624E - JESLOG parameter has an invalid value
Parent topic: JCLCM Error Messages


JCLCM0800 - JCLCM0899

  • JCLCM0801I Event-job-concluded. Job ended normally
  • JCLCM0802I Event-job-concluded. Job ended abnormally
  • JCLCM0803I Event-job-concluded. Job failed - JCL error
  • JCLCM0804I Event-job-concluded. Job scanned - No Errors
  • JCLCM0805I Event-job-concluded. Job scanned - JCL error
  • JCLCM0806I Event-job-concluded. Job flushed - No JOB stmt
  • JCLCM0807I Event-job-concluded. Job flushed - Bad JOB stmt
  • JCLCM0808I Event-job-concluded. Job flushed by User Exit req
  • JCLCM0809I Event-job-concluded. Job copied
  • JCLCM0810I Event-job-concluded. Job cancelled
  • JCLCM0811I Event-job-concluded. Job authentication failed
Parent topic: JCLCM Error Messages


JCLCM0900 - JCLCM0999

  • JCLCM0900E job-number job-name User Exit shut down due to a failure
    A failure in the user exit has forced the JCL engine to shut down the user exit.
  • JCLCM0901I job-number job-name Event-job-ready action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0902I job-number job-name Event-job-flushed action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0903I job-number job-name Event-job-started action is: explanation
    The user exit has requested this action to be taken for this event.
  • JCLCM0904I job-number job-name Event-job-JCL-error action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0905I job-number job-name Event-job-ended action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0906I job-number job-name Event-TSO-started action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0907I job-number job-name Event-TSO-ended action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0908I job-number job-name Event-step-ready action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0909I job-number job-name Event-step-started action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0910I job-number job-name Event-step-ended action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0911I job-number job-name Event-step-bypassed action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0912I job-number job-name Event-CALL-ready action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0913I job-number job-name Event-CALL-started action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0914I job-number job-name Event-CALL-ended action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0915I job-number job-name Event-RUN-ready action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0916I job-number job-name Event-RUN-started action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0917I job-number job-name Event-RUN-ended action is: explanation
    The user exist has requested this action to be taken for this event.
  • JCLCM0918I job-number job-name Event-before-PGM-call action is: explanation
    The user exit has requested this action to be taken for this event.
  • JCLCM0919I job-number job-name Event-after-PGM-call action is: explanation
    The user exist has requested this action to be taken for this event.
Parent topic: JCLCM Error Messages


JCLCM1000 - JCLCM2000

  • JCLCM1475S: Fatal RTS error: Out of Space. Work suspended until operator input received.
    The JCL engine has received an Out of Space error from the Run Time System. Processing has been suspended until an operator allows it to continue.
  • JCLCM1500S:VSAM Shareoption Manager Error. . DS: DATASET NAME. Action: OPEN, CLOSE, Intent INPUT, I-O, OUTPUT, RC: Error Code Reason: Detailed Reason Code.
    The VSAM Shareoption Manager has encountered an error when processing the shareoption request for the Datatset.
  • JCLCM2000S: Unable to acquire global lock for job JOB NAME.
    A connection error occurred when requesting an enqueue on the job from the Global Lock Manager.
Parent topic: JCLCM Error Messages


JCLCM1475S: Fatal RTS error: Out of Space. Work suspended until operator input received.

The JCL engine has received an Out of Space error from the Run Time System. Processing has been suspended until an operator allows it to continue.

Resolution:

Correct the problem by freeing up disk space. Then, using the browser interface ESMAC, select the active queue and the job that is suspended. It will be awaiting a Reply. In the Reply field enter a value (any value) and click Reply. The batch initiator will shut down and a new one will start up, and processing will continue.

Parent topic: JCLCM1000 - JCLCM2000


JCLCM1500S:VSAM Shareoption Manager Error. . DS: DATASET NAME. Action: OPEN, CLOSE, Intent INPUT, I-O, OUTPUT, RC: Error Code Reason: Detailed Reason Code.

The values for it can be:

RC:

0 | OK
1 | Invalid dataset name
2 | Invalid action
3 | Invalid intent
4 | Cluster name error
5 | Error enqueuing on SYSVSAM CLUSTER NAME...B resource
6 | Error enqueuing on I/O resources (not covered by access denied error)
7 | Can't get enqueues on this dataset
8 | Wrong calling mode (jcl,cics or ims allowed)
9 | Any missing parameter error, reason-code holds parameter number
10 | An error when trying to reinstate an ENQ in the test section
11 | An error occurred when removing an expected CICS ENQ before adding a new one

Reason Codes:

0 | OK
1 | Not a valid DS name
2 | DS not found in catalog
3 | Not a VSAM dataset
4 | No shareoption value for the dataset
5 | Wrong catalog record extended-type value
6 | Error in set-cl-name (wrong size)
7 | No name was found in the DATA or INDEX catalog entry for the parent cluster
8 | Name is too long or invalid
9 | The catalog record for the parent (cluster name) of a DATA or INDEX entry was not found
10 | The RELATE entry for an AIX was not found in the VCAT-OPER catalog field
11 | The RELATE entry of the AIX record was found but the value is invalid
12 | Error getting busy enqueue for this dataset
13 | An existing enqueue prevents this enqueue
14 | ES_SHAREOPT!=Y, shareoptions not enabled
15 | The PATHENTRY entry for a PATH was not found in the VCAT-OPER catalog field
16 | The PATHENTRY entry of the PATH record was found but the value is invalid
Parent topic: JCLCM1000 - JCLCM2000


JCLCM2000S: Unable to acquire global lock for job JOB NAME.

Parent topic: JCLCM1000 - JCLCM2000


JCLGN Error Messages

Select the number of the message you require details about:

  • JCLGN0001U job-number job-name MISSING SYSUT1
    The DD statement for SYSUT1 is missing from your JCL.
  • JCLGN0002U job-number job-name INVALID SYSUT1
    The dataset organization for SYSUT1 is invalid.
  • JCLGN0003U job-number job-name MISSING SYSUT2
    The DD statement for SYSUT2 is missing from your JCL.
  • JCLGN0004U job-number job-name INVALID SYSUT2
    The dataset organization for SYSUT2 is invalid. Only sequential datasets and members of a PDS dataset can be specified on the SYSUT2DD statement.
  • JCLGN0005U job-number job-name I/O ERROR ON SYSUT1
    An error has occurred when accessing the dataset specified by the SYSUT1DD statement.
  • JCLGN0006U job-number job-name I/O ERROR ON SYSUT2
    An error has occurred when accessing the dataset specified by the SYSUT2DD statement.
  • JCLGN0007U MISSING SYSPRINT
  • JCLGN0008U INVALID SYSPRINT
  • JCLGN0009U MISSING SYSIN
  • JCLGN0010U INVALID SYSIN
  • JCLGN0011U I/O ERROR ON SYSPRINT
  • JCLGN0012U I/O ERROR ON SYSIN
  • JCLGN0100U MISSING DD STATEMENT FOR filename
    You have referenced a data set from a program but your JCL does not include a DD entry for it.
  • JCLGN0101U INVALID DSORG FOR filename
    The data set's DSORG is inappropriate for the operation you are trying to perform.
  • JCLGN0102U I/O ERROR ON filename
  • JCLGN0103U I/O STATUS = file status
  • JCLGN0104U MFJGENER ABENDED system code
    See preceding messages for details of the error.
  • JCLGN0110I number RECORDS COPIED FROM SYSUT1 TO SYSUT2
  • JCLGN0111I number RECORDS COPIED
  • JCLGN0112I TO MEMBER NAME %
  • JCLGN0200E PARAMETER TOO LONG [value]
  • JCLGN0201E CONTINUATION ERROR [value]
  • JCLGN0202E MISMATCHED QUOTES OR PARENTHESIS [value]
  • JCLGN0210E UNRECOGNIZED OPERATOR KEYWORD [value]
  • JCLGN0211E DUPLICATE CONTROL STATEMENT [value]
  • JCLGN0220E UNRECOGNIZED OPERAND KEYWORD [value]
  • JCLGN0221E DUPLICATE OPERAND KEYWORD [value]
  • JCLGN0222E TOO MANY OPERANDS [value]
  • JCLGN0223E INVALID OPERAND VALUE [restriction]
    The restriction shows the values permitted.
  • JCLGN0224E UNEXPECTED OPERAND [%]
    Too many operands are present.
  • JCLGN0225E EXPECTED OPERAND MISSING [parameter]
    A required operand is missing from parameter.
Parent topic: JCL Error Messages


JCLIM Error Messages

Select the number of the message you require details about:

  • JCLIM0001U job-number job-name INVALID EXEC STATEMENT PARM
    MFJIMS expects parameter data on the EXEC statement, but the data has not been supplied.
  • JCLIM0002U job-number job-name INVALID PROGRAM TYPE PARM
    The program type specified in the PARM operand must be BMP (or IFP) or DLI (or DBB).
  • JCLIM0003U job-number job-name MISSING PROGRAM NAME PARM
    The program name has not been specified in the PARM operand.
  • JCLIM0004U job-number job-name MFIMS OPTION NOT INSTALLED
    MFJRRC00 is unable to locate the MFIMS software option.
  • JCLIM0005U - Program Parm Contains Invalid Character n
  • JCLIM0201U MISSING DDITV02 DD STATEMENT
  • JCLIM0202U INVALID DDITV02 PARM STATEMENT
  • JCLIM0203U INVALID DDITV02 PROGRAM PARM
  • JCLIM0204U I/O ERROR ON DDITV02 DATASET
  • JCLIM0205U - Missing DD Statement nnnnnn
  • JCLIM0206U - Invalid Dsorg For n
  • JCLIM0207U - Invalid/Missing Control Statement On n
  • JCLIM0208U - I/O Error On n
Parent topic: JCL Error Messages


JCLPT Error Messages

Message | Description
JCLPT0001E PRINT/PUNCH statement not first | The first statement in the control data set must be either a PRINT or a PUNCH statement.
JCLPT0002E MEMBER INVALID - TYPORG not PO | A MEMBER statement is invalid as the specified TYPORG is not PO. The default value for TYPORG is PS.
JCLPT0003E INVALID COMMAND - no MAXNAME parameter | If a MEMBER statement is present in the control data set, MAXNAME must be specified either in the PRINT or in the PUNCH statement.
JCLPT0004E INVALID COMMAND - RECORD command already found | When the RECORD and MEMBER statements are used, at least one MEMBER statement must precede the first RECORD statement.
JCLPT0005E MAXNAME parameter is too small | The specified MAXNAME parameter is less than the total number of member names specified in subsequent MEMBER statements.
JCLPT0006E INVALID COMMAND - NO NAME parameter | A NAME parameter is missing from the MEMBER statement.
JCLPT0007E MORE THAN TWO TITLE CARDS | Only two TITLE statements might be included for each use of MFJPTPCH. The first TITLE statement defines the title and the second statements defines the subtitle.
JCLPT0008E Unrecognised command - [command] | A command statement syntax error.
JCLPT0009E SYSIN IS EMPTY | The specified SYSIN is empty.
JCLPT0010E MISSING COMMAND PRECEDING COL 71 | There are no command statements in columns 1 - 71 of the control data set.
JCLPT0011E TYPORG value not found | No value is specified for the TYPORG parameter.
JCLPT0012E TYPORG value is not PO or PS - [value] | The value of TYPORG must be either PS or PO.
JCLPT0013E TOTCONV value not found | No value is specified for the TOTCONV parameter.
JCLPT0014E TOTCONV value is not XE or PZ - [value] | The value of TOTCONV must be either XE or PZ.
JCLPT0015E Option only valid for PRINT - [command] | The specified control statement can only be coded with the PRINT statement.
JCLPT0016W Option is not supported (ignored) - parameter | The specified parameter is not currently supported and is ignored.
JCLPT0017E Unrecognised keyword - [parameter] | The specified parameter for PRINT or PUNCH is not valid.
JCLPT0018E parameter value not found | No value is specified for this parameter.
JCLPT0019E parameter value is not numeric | The value of the specified parameter should be numeric.
JCLPT0020E Allocation failure for [parameter] | Memory allocation failed for the specified parameter.
JCLPT0021E No RECORD command parameters found | No parameters are specified for the RECORD statement.
JCLPT0022E FIELD specification not found | No parameter value is specified for the RECORD FIELD statement.
JCLPT0023E MAXFLDS parameter is too small | The specified MAXFLDS parameter is less than the total number of FIELD parameters specified in subsequent RECORD statements.
JCLPT0024E FIELD length value not found | No length is specified in the RECORD FIELD statement.
JCLPT0025E FIELD length value is not numeric - [length] | The value of the FIELD length must be numeric.
JCLPT0026E FIELD input location is not numeric - [input location] | The FIELD input location must be numeric.
JCLPT0027E FIELD conversion option is invalid - [conversion] | The specified FIELD conversion option is not valid.
JCLPT0028E FIELD output location is not numeric - [output location] | The FIELD output location must be numeric.
JCLPT0029E MAXGPS parameter is too small | The specified MAXGPS parameter is less than the total number of IDENT parameters specified in the subsequent RECORD statements.
JCLPT0030E IDENT length value not found | No length is specified in the RECORD IDENT statement.
JCLPT0031E IDENT length value is not numeric - [length] | The value of the IDENT length must be numeric.
JCLPT0032E IDENT length value is greater than 8 - [length] | The IDENT length must not exceed eight bytes.
JCLPT0033E Closing quote for IDENT text was not found | The literal that identifies the last record of a record group must be enclosed in apostrophes.
JCLPT0034E IDENT text is shorter than the specified length - [length] | The IDENT text is shorter than the length specified in the control statement.
JCLPT0035E IDENT text is longer than the specified length - [length] | The IDENT text is longer than the length specified in the control statement.
JCLPT0036E IDENT location is not numeric - [location] | The starting location of the field that contains the identifying name in the input records must be a numeric.
JCLPT0037E No TITLE command parameters found | The TITLE statement is specified without any parameters.
JCLPT0038E ITEM location is not numeric - [location] | The output location specified in the TITLE ITEM statement must be numeric.
JCLPT0039E Closing quote for ITEM text was not found | The title or the subtitle literal specified in the TITLE statement must be enclosed in apostrophes.
JCLPT0040E Continuation not found | No continuation character was found in column 72 in SYSIN.
JCLPT0041E Continuation starts before Col 4 | Continuation must start in column 4.
JCLPT0042I SYSUT1 is partitioned, but TYPORG is PS - directory assumed | SYSUT1 is a partitioned dataset, but the specified TYPORG is PS. PO organization is assumed for SYSUT1.
JCLPT0043E SYSUT1 is sequential, but TYPORG is PO | SYSUT1 is a sequential dataset, but the specified TYPORG is PO.
JCLPT0044E Invalid SYSUT1 record format - [recfm] | SYSUT1 can have only fixed, variable and line sequential record formats.
JCLPT0045E SYSUT2 record length exceeds maximum | The maximum record length of SYSUT2 is 145.
JCLPT0046E Invalid SYSUT2 record format - [recfm] | The record format of SYSUT2 is always FBA.
JCLPT0047W Incorrect RECORD statement - FIELD extends beyond sysut2 LRECL | The FIELD must not exceed the SYSUT2 LRECL.
JCLPT0048E Continuation not started in 4-16 | Continuation must be between columns 4 and 16.
JCLPT0049E SYSPRINT record length must be 121 | The record length of SYSPRINT must be 121.
JCLPT0050E I/O error on [filename] | I/O error on filename.
JCLPT0051E MEMBER not valid for the action [action] - TYPORG not PO | No MEMBER statements were found but the specified TYPORG is not PO.
JCLPT0052E SYSIN record length must be 80 | The record length of SYSIN must always be 80.
JCLPT0053E SYSUT1 concatenation error - Concatenated libraries are not supported | SYSUT1 concatenation is not currently supported.
JCLPT0054E Invalid syntax - [command] | A command statement syntax error.
JCLPT0055W Command "command-name" is not currently supported | The specified command is not currently supported.
JCLPT0056E File status is [status code] | Specifies the returned file status code.
JCLPT0057E IDENT location is greater than SYSUT1 record length - [location] | The specified IDENT input-location must not be greater than the SYSUT1 LRECL.
JCLPT0058E FIELD output location is greater than SYSUT2 record length - [location] | The specified FIELD output location must not be greater than the SYSUT2 record length.
JCLPT0059E Fatal error returned by [utility] | The utility returned an error.
JCLPT0060E Error writing to SYSUT2 - File status is [status code] | The SYSUT2 write failed with the specified file status code.
JCLPT0061E Fatal error returned by CBL_DIR_SCAN_START - [status-code] | CBL_DIR_SCAN_START has failed.
JCLPT0062E Error returned by CBL_DIR_SCAN_READ - [status-code] | CBL_DIR_SCAN_READ has failed.
JCLPT0063E Error reading SYSUT1 - File status is [status-code] | The SYSUT1 read failed with the specified file status code.
JCLPT0064E IDENT location is not found | The specified IDENT location is not found.
JCLPT0065E ERROR READING SYSIN - File status is [status-code] | The SYSIN read failed with the specified file status code.
JCLPT0066E DDNAME SYSIN cannot be opened - File status is [status-code] | OPEN failed for SYSIN.
JCLPT0067W MEMBER [member name] cannot be found | The specified SYSUT1 member cannot be found.
JCLPT0068E DDNAME SYSUT1 cannot be opened - File status is [status-code] | OPEN failed for SYSUT1.
JCLPT0069E DDNAME SYSUT2 cannot be opened - File status is [status-code] | OPEN failed for SYSUT2.
Parent topic: JCL Error Messages


JCLUT Error Messages

Select the number of the message you require details about:

  • JCLUT0001E job-number job-name Control statement error explanation
  • JCLUT0005E job-number job-name Continuation error
  • JCLUT0006E
  • JCLUT0007E
  • JCLUT0008E
  • JCLUT0009E
  • JCLUT0010E
  • JCLUT0011E "keyword" is not compatible with a preceding keyword
  • JCLUT0012E "keyword" is invalid keyword value.delimiter, descriptor or type is improper, or duplicated
  • JCLUT0100S MISSING "filename"
    The file cannot be found
  • JCLUT0101S INVALID "filename"
  • JCLUT0102S I/O ERROR ON "PDS member name"
    The PDS member does not exist or is invalid.
  • JCLUT0103S UTILITY "utility-name" ABENDED
    An error has caused the utility to abend.
  • JCLUT0104S DUPLICATE MEMBER "PDS-member-name"
    You have tried to create a PDS member but a member with that name already exists.
  • JCLUT0105S CATALOG ERROR ON "dataset-name"
  • JCLUT0106S RETURN CODE IS "value"
  • JCLUT0107S
  • JCLUT0108S
  • JCLUT0201I MEMBER "PDS-member-name" NOT FOUND
    You have tried to access a PDS member but there is no catalog entry for it.
  • JCLUT0202I RECORDS COPIED "number"
  • JCLUT0203I MEMBERS NAME "PDS-member-name"
  • JCLUT0204I MEMBERS WRITTEN TO OUTPUT DD "number"
  • JCLUT0205I INDD=OUTDD="filename", COMPRESS IN PLACE IGNORED
  • JCLUT0206S Character set mismatch. Copied without conversion
Parent topic: JCL Error Messages


JCLZZ9999S job-number job-name MESSAGE UNDEFINED MESSAGECODE

No message text has been defined for the specified message code.

Resolution:

Report the problem to Micro Focus Support.

Parent topic: JCL Error Messages


SORT - MFJSORT Error Messages

Select the number of the message you require details about.

Some message IDs are followed by a line of asterisks. The right-most asterisk indicates the position of the error in the preceding line. The message text is shown on the following line.

  • SORT000 - SORT099
  • SORT100 - SORT199
  • SORT200 - SORT399
Parent topic: JCL Error Messages


MFJSORT Summary Messages

After successfully completing a SORT operation, MFJSORT displays a summary of the operation, including information such as the number of records read and written. The following is an example of this summary information:

SORT204I: ********************* Sort Statistics *********************

SORT 205I: INPUT file 'SORTIN'

1267 record(s) input.

1252 record(s) used.

SORT206I: OUTPUT file 'SORTOUT'

1210 record(s) used.

1240 record(s) output.

SORT207I: OUTFIL file 'SORTFIL;

2 record(s) used

6 record(s) output

SORT399I: End of Micro Focus MFJSORT Utility

This provides the following information:

  • A total of 1267 records were read.
  • Of the 1267 records read, MFJSORT used 1252. MFJSORT might read a record but not use it because, for example, the record could fail to meet the conditions specified in an OMIT or INCLUDE statement, or records could be combined through the action of the SUM statement.
  • MFJSORT output 1210 records. This could be less than the number of records used because some of the released records failed to satisfy conditions specified in the OUTFIL OMIT or OUTFIL INCLUDE statements.
  • 1240 sorted records were written to SORTOUT. The 30 extra records above the number of returned records might be report headers or trailers.
  • For records for OUTFIL DD statements, MFJSORT used 2 records and output 6. The reasons for the difference between these numbers are the same as described above.

If the number of records read is the same as the number of records released, the messages for those two pieces of information are combined. Similarly, the messages showing the number of records returned and written are combined if their numbers are the same.

Parent topic: JCL Error Messages
Related information
SORT - MFJSORT Error Messages


JES Messages

These messages can be printed by the Job Entry Subsystem when a job is submitted or when output is printed.

Message | Description
JES000002E JCL parser not avaliable.
JES000003Ennnnn duplicates an existing job number. | The job # specified during submission duplicates an already existing job #. You need to reset your job # mechanism.
JES000011E Batch Spool File Error; Status nnnnnn. | While trying to access the spool, an unexpected file status was encountered. (nnnnn)
JES000012I Batch Input Spool has been cold-started. | There was no casspool.dat file located in the same directory as the System catalog that this server is configured to use. A new one has been created.
JES000013I JOB nnnnn requeued for restart at xxxxxx. | The job nnnnn has been queued for restart at the step (and where applicable the procstep) specified by xxxxxx.
JES000014E JOB nnnnn not restarted. Job, Step or Procstep xxxxxx restart information not found. | The job nnnnn cannot be restarted because it does not contain the specified step (and where applicable the procstep) specified by xxxxxx.
JES000015I JOB nnnnn does not exist for restart. | The job specified does not exist. This may be because the job has been deleted by another user or by the spool housekeeping process.
JES000016E JOB nnnnn not executed. Undefined JES error, FEP-RC: (RC). | An attempt was made to restart a job that wasn't run with restart in effect, or files associated with the job have been deleted.
JES000017E JOB nnnnn restart not allowed at Step/Procstep xxxxxx. | This error is displayed when the job or the step specified is non-restartable.
JES000019E Unable to allocate job number for job. | A job number could not be allocated for this job. Check the range of available job numbers. See also the JCLCM0164A message.
JES000024I Batch Printer: xxxxxx | The printer named ‘xxxxxx’ has been initialized.
JES000025E Printer not found: xxxxxx | The printer named ‘xxxxxx’ was not located while enumerating through the printers defined on this machine.
JES000025I Printer not found: xxxxxx | The printer named ‘xxxxxx’ cannot be found but a printer exit is defined. The printer exit will handle the condition.
JES000026O Exit Module: xxxxxxxx | The batch printer specified in the previous JES000024I message is using a printer exit named ‘xxxxxxxx’
JES000027E Printer assignment failed. RC = nnnnn | A failure occurred while trying to set the default printer for the batch printer sep. A printer matching the specified name was found, but the setting as default printer for this SEP failed.
JES000028E Load fialed for exit Module: xxxxxxxx | A printer was found which matches the specified printer name, but the exit routine specified for this batch printer (xxxxxxxx) was not found.
JES000029I Locating batch printer: xxxxxx | An information message issued when a batch printer initializes, indicating which printer device is being searched for by this batch printing SEP
JES000029I xxxxxx on yyyyyy | Document xxxxxxxx is being printed by the batch printer on printer yyyyyyyy
JES000030E xxxxxx | While trying to print the document listed in the previous JES000029I message the spool tried to access the cataloged entry for this sysout dataset. There was a failure upon accessing the catalog specified by the message message
JES000031E Printer open failed. RC = nnnnn | A failure occurred in either the API call PC_PRINTER_OPEN or the API call PC_PRINTER_SET_FONT that occurs when a batch SEP tries to drive sysout output through to the defined printer. The failure return code is nnnnn
JES000032E Printer write failed. RC = nnnnn | A failured occurred while trying to write to the printer device attached to the batch printing SEP. The return code is documented in the API documentation for PC_PRINTER_WRITE
JES000033E Printer error accessing spool data: xxxxxx | A failure occurred while trying to access the physical dataset associated with sysout entry. The file status code of the failure is indicated by the message message.
JES000034E JOBnnnnn - TIME parameter exceeds 65533 seconds after applying class multiplier (xxxxxx).
JES000035E JOBnnnnn - TIME parameter exceeds 65533 seconds after applying class multiplier (xxxxxx)
JES000036E nnnnn xxxxxx
JES000040I SSTM environment established successfully. nnnnn
JES000041E SSTM initialization failure nnnnn
JES000042I SSTM not enabled: nnnnn
JES000050E JCL parsing error: RC = nnnnn. | While attempting to compile a piece of JCL for future execution, a failure occurred. The return code for the failure is documented by nnnnn
JES000051I Job Entry Subsystem (JES) services initialized. | The JES services for the process have been initialized
JES000052E Job Entry Subsystem (JES) initialization failed. Environment improperly configured. xxxxxxxx When a server is started, JES performs some validation checks to ensure that databases can be properly allocated. These fail messages indicate that this Initial Validation Process detected an error. The error indicates that the IVP was unable to allocate and test DSN on the system catalog. The likely causes are:
  • an error on the JES set tab
  • the System Catalog name is invalid or unusable
  • the Default Allocation Location is invalid or unusable
  • the environment variable MFALLOC_PROP is set
JES000120S Failed to get spool record lock. Type <lock type>, Job# <job number>, Seq# <sequence code>, Loc: <lock point> | This error, together with JES000121S is generated by the spool module when it fails to obtain the required lock on a record. The number of times the module retries to obtain the lock can be adjusted via the environment variable: CASSPOOL_LOCK_RETRY_COUNT.
JES000121S Failed to get spool record. FS: <file status>, Type: <lock type>, Job# <job number>, Seq# <sequence code>, Loc: <lock point> | This error, together with JES000120S is generated by the spool module when it fails to obtain the required lock on a record. The number of times the module retries to obtain the lock can be adjusted via the environment variable: CASSPOOL_LOCK_RETRY_COUNT.
JES000130E Note JES000011 Error - New casspool indexes may need generating. See error description in product docs

As part of an enhancement to improve performance when browsing the spool queue of an Enterprise Server, you must update the casspool file for any Enterprise Server created before Enterprise Developer 2.2 Update 1, before you can submit jobs to it.

To update the casspool for each Enterprise Server, from a command prompt, run fixcasspool.bat, located in %COBDIR%\bin and %COBDIR%\bin64, using the following syntax:

fixcasspool.bat casspool.dat backup.dat
Where:
casspool.dat
The spool file, located in the same directory as the Enterprise Server's system catalog, that will be updated.
backup.dat
A file that will be created with a backup of the old casspool.dat file. If backup.dat already exists, the update is not run.
JES000140E Printer Exit reported error printing <dataset information>. RC = <return code>. Where:
dataset information
Consists of the following details separated by colons (:):

UserId:JobName:JobNumber:StepName:ProcedureStepName:DDName:StepNumber:ProcedureStepNumber:RecordClass

return code
The return code from the printer exit.

The following is an example error message:

JES000140E Printer Exit reported error printing SYSAD:MCDPP302:01005:STEP01::SYSUT2:000001:000000:A. RC = +000000009

JES000222E JOB nnnnn cancelled by operator | Job # job-number was cancelled via the casout command -k option or via the ESMAC Spool view function
JES000913E JOBnnnnn User xxxxxx has an invalid password or no longer has auth to exec JCL.
JES000914E JOBnnnnn User xxxxxx is not a surrogate of User zzzzzz.
JES000915E JOBnnnnn User xxxxxx does not have authority to submit job zzzzzz.
Parent topic: JCL Error Messages


Enterprise Server Security

Contains information and procedures for all aspects of securing an Enterprise Server installation.
  • 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
Related concepts
User Impersonation for CICS and JCL


Securing an Enterprise Server Installation

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
  • MLDAP ESM Module
  • Configuring Operating System Security: osesm
  • Configuring Security using Active Directory
  • Configuring Security Using OpenLDAP
  • Examples
  • Managing LDAP Security Manager from the Enterprise Server UI
  • ESF LDAP Security Administration Web Interface
  • Migrating from Enterprise Server Early Versions
  • Security Reference Information
  • Using External Security Facility (ESF) Features
  • Glossary
Parent topic: Enterprise Server Security


Architecture and Overview

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
  • Threat Models
  • Security Architecture
Parent topic: Securing an Enterprise Server Installation


Threat Models

In this release of Enterprise Server, the security features are designed to address a particular "threat model". A threat model is a description of the kinds of unauthorized actions the system has to protect against. Security issues that don't fall under the threat model have to be addressed outside Enterprise Server, using features such as operating system security and corporate policies.

The current Enterprise Server threat model trusts the applications that run on your enterprise server, and assumes the system is reliable. The threats it addresses are attempts to impersonate legitimate users, and legitimate users making illegal requests to access or modify resources or features.

Enterprise Server security is not designed to prevent developers from creating applications, running under Enterprise Server, that misuse data or resources. Enterprise Server does not prevent applications from using SYSTEM or COBOL library routines such as CBL_WRITE_FILE to alter data or run arbitrary commands with the permissions of the account used by Enterprise Server, or from calling operating system APIs. Appropriate operating system administration can mitigate many of these threats. Micro Focus recommends that you institute processes and procedures appropriate for your organization to ensure trust for your applications.

Parent topic: Architecture and Overview


Security Architecture

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

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)

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

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

    The CAS ESM Module (casesm) uses the Enterprise Server legacy security definitions (stored in the CICS resource tables). This is the model used in earlier releases (5.0 and lower),

    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

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.

There are two types of authorization queries used by the External Security Facility:

  • The first, used by Enterprise Server when processing MSS application requests, implements mainframe-style permissions. In this approach, a user is granted a permission level that includes all the "lower" permissions (write access implies read access and so on).
  • The second type of query is currently used only by MF Directory Server. It implements more modern discretionary access controls (DACs). In this approach, permissions are separate from one another. For example, a user can have write access but not read access to a resource.
Note: This issuing of security queries during MSS processing is intended to emulate, as far as is feasible, the behaviour found on IBM mainframe platforms. For more information on these security queries, refer to your mainframe documentation.
Parent topic: Security Architecture


Designing the Security Policy

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

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

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

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

  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

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin.

    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.

    This parameter is currently ignored by the ESM Module.
    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.

    This parameter is currently ignored by the ESM Module.

    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

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

  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

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

  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

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

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:
  • The default MFDS Internal Security can only be used by itself. If you use this, you cannot configure any other security managers.
  • In a production environment, you should use external security managers rather than the MFDS Internal Security.
  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure, click Security.
  2. Click on the MF Directory Server tab.
  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.

    Note: To configure the MF Directory Server to use the same external security managers as configured for default Enterprise Server instances (this is recommended where possible), check Use default ES Security Manager List and click Apply. The MF Directory Server tab should now show the same security managers as the Default ES Security tab.
  7. To apply the configured security options to the MF Directory Server, check the Restrict administration access on the MF Directory Server tab.

    This opens a login screen which requires credentials to be input that have sufficient permission level to allow the requested security configuration changes. The permissions check is carried out using the requested security options.

    Note:
    • If the input credentials are incorrect or do not have sufficient permissions to change the security options, an error is displayed and the administration access remains unrestricted.
    • If any security configuration changes are requested when Restrict administration access is already checked, a login screen is displayed to confirm that the administrator has permission to change the security configuration using the current security configuration settings and then, again, with the changed security configuration.
Parent topic: Configuring Enterprise Server Security


Customizing the Security Settings for an Enterprise Server Instance

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

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

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

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

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 its Mainframe Subsystem Support user attributes (such as user priority) have been changed, or 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

esfadmin is a command-line utility that calls the ESF Admin API to request administrative actions against ESMs. It is a part of Enterprise Developer and Enterprise Server, and can be found in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin and \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.

The ESF administration facility makes some security checks before it attempts to process an administration request:

  1. It requires the user be successfully signed into ESF. This requirement can be disabled for LIST commands using the allow-list configuration option.
  2. The MLDAP ESM Module checks to see if the user has execute permission for a resource with the same name as the command (for example ADDUSER) under the class AdminAPI. See the complete list of esfadmin sub-commands in the section esfadmin Sub-commands. This class is optional, and if there is no applicable rule, access is allowed.
  • About the esfadmin Command
  • esfadmin Sub-commands
Parent topic: Securing an Enterprise Server Installation


About the esfadmin Command

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

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

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 is 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 is not actually an attribute of a user. 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.
  • If you are listing many users, or have many groups, it might take a long time for LISTUSER to generate the group-membership information. You can tell LISTUSER not to include group membership by adding COMPUTED=NO to the esfadmin command line.
  • 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.
  • By default, the LISTUSER, LISTGROUP, LISTCLASS, and LISTRESOURCE commands will perform wildcard searches if you specify a name with the "*" wildcard character. For example, esfadmin LISTUSER USER=A* will list all users with names beginning with "A".

    This might not be the desired behavior, particularly when listing resource rules, since those often contain wildcard characters. You can tell the LIST commands to treat the "*" character as a literal character (and not a wildcard) by adding LITERAL=YES to your esfadmin command line.

  • 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. Alternatively, use the new ADDMEMBER and DELMEMBER commands.
  • 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. Alternatively, use the new ADDACE, ALTACE, and DELACE commands.

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

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

The esfadmin command can use the following sub-commands:

  • ADDACE, ALTACE, and DELACE
  • ADDCLASS and ALTCLASS
  • ADDGROUP and ALTGROUP
  • ADDMEMBER and DELMEMBER
  • ADDRESOURCE and ALTRESOURCE
  • ADDUSER and ALTUSER
  • DELCLASS
  • DELGROUP
  • DELRESOURCE
  • DELUSER
  • LISTCLASS
  • LISTGROUP
  • LISTREFERENCES
  • LISTRESOURCE
  • LISTUSER
  • SETOPTIONS
  • SETPASSWORD
Parent topic: Configuring External Security Facility (ESF) from the Command Line
Related reference
esfadmin Command Syntax


ADDACE, ALTACE, and DELACE

Description

Add an access control entry (ACE) to the access control list (ACL) of a resource access control rule, replace one ACE with another, or remove an ACE from an ACL. The resource rule's ACL is updated by adding, modifying, or removing the ACE, without affecting other ACEs in the list. This is usually simpler and safer than changing the entire list with ALTRESOURCE.

ALTACE combines a DELACE of the old ACE value with an ADDACE of the new one. The old value must exist.

Required parameters

CLASS=name
Name of the class containing the resource to be updated.
RESOURCE=name
Name of the resource to update.
ACE=ACE string
The ACE to add, remove, or change, for example allow:OPERATOR group:alter.
VALUE=ACE string
For ALTACE only, the new value of the ACE being modified.
Parent topic: esfadmin Sub-commands


ADDCLASS and ALTCLASS

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

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


ADDMEMBER and DELMEMBER

Description

Add a member (user) to a group, or remove a member from a group. The group's membership list is updated by adding or removing the user, without affecting other users in the list. This is usually simpler and safer than changing the entire list with ALTGROUP.

Note: This command does not affect a user's default group. To remove a user from their default group, use ALTUSER.

Required parameters

GROUP=name
Name of the group
MEMBER=name
Name of the user to add or remove. USER=name can also be used.
Parent topic: esfadmin Sub-commands


ADDRESOURCE and ALTRESOURCE

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

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:

PRIORITY=integer
MSS user priority (0-255).
TIMEOUT=integer
MSS user timeout in minutes.
OPCLASS=integer
MSS operator class (usually 0).
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.
DEFGROUP=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). The PASSWORD attribute is supported for ADDUSER only. To change an existing user's password, use the SETPASSWORD sub-command.
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.
GRPPFX=string
MSS group prefix (currently unused).
OPID=xxx
MSS operator ID (three characters).
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

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

Description

Delete a group.

Required parameters

GROUP=name
Name of the group to delete.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


DELRESOURCE

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


DELUSER

Required parameters

USER=name
Name of the user to delete.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


LISTCLASS

Description

List the classes.

Required parameters

CLASS=pattern
Pattern name, optionally with “*” wildcards.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


LISTGROUP

Description

List the groups.

Required parameters

GROUP=pattern
Group name, optionally with “*” wildcards.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


LISTREFERENCES

Description

List the references to and from a user, group, class, or resource.

Security objects (users, groups, classes, and resources) refer to one another in various ways. A user may refer to a default group, and be referred to by groups as a member of those groups. A user may also be referred to by access control entries (ACEs) in resource rules. Groups refer to users and may be referred to by users and resources. Resources refer to users and groups and are referred to by the class they belong to. Classes refer to the resources they contain.

Often administrators need to understand these relationships, for example to find out what explicit permissions a group has been granted, or to ensure a user has been removed from all groups before deleting that user. The LISTREFERENCES command can be used to discover them.

Each reference is listed with three attributes: its name, its type (user, group, etc), and a comment indicating how it is related to the object being queried.

Note: Currently LISTREFERENCES does not include references due to ACEs with wildcard user or group names, such as allow:*:read.

Required parameters

For listing a user's references:

USER=name
The user to list references for.

For listing a group's references:

GROUP=name
The group to list references for.

For listing a class's references:

CLASS=name
The class to list references for.

For listing a resource's references:

RESOURCE=name
The resource to list the references for. Usually the optional CLASS parameter will also be specified.

Optional parameters

CLASS=name
When listing a resource, specify the class of the resource. If this is not specified, references for matching resources in all classes will be listed.
LITERAL=NO
Tells ESF to treat "*" characters as wildcards, and list references for all matching objects.
The command esfadmin LISTREFERENCES USER=SYSAD, run against the sample security configuration supplied with Enterprise Server, produces output similar to this:
ESF EM 1000 I ESM1: MLDAP ESM initialized
ESF MI 200 I Loaded module mldap_esm for ESM (1) "mldap_esm": MLDAP ESM version
2.0.2
ESF PI 101 I External Security Manager version 2.1.0 initialized

LIST Command results:

List      1 contains      6 items.
NAME=CICSUSER
TYPE=USER
COMMENT=The user itself

NAME=ALLUSER
TYPE=GROUP
COMMENT=User's default group

NAME=ALLUSER
TYPE=GROUP
COMMENT=Explicit group member

NAME=DEVGROUP
TYPE=GROUP
COMMENT=Explicit group member

NAME=*
TYPE=RESOURCE
COMMENT=Class TCICSTRN, ACE allow:CICSUSER:read

ESF EM 1002 I ESM1: MLDAP ESM exiting
Command processing completed successfully

The list output shows the following references: the CICSUSER object itself, its default group, the groups it is an explicit member of, and a resource that has an ACL that names the user specifically.

Parent topic: esfadmin Sub-commands


LISTRESOURCE

Description

List the resources.

Required parameters

RESOURCE=pattern
Resource name, optionally with “*” wildcards.
CLASS=name
Name of class to search.

Optional parameters

LITERAL=YES
Prevents the “*” character from functioning as a wildcard. This lets you list specific resources with names that include wildcards. For example, use esfadmin LISTRESOURCE CLASS=DATASET RESOURCE=** LITERAL=YES to list the "**" resource rule in the DATASET class.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


LISTUSER

Description

List the users.

Required parameters

USER=pattern
User name, optionally with “*” wildcards.

Optional parameters

COMPUTED=NO
Disables the generation of the GROUPS attribute in the output, which lists groups the user belongs to. This attribute must be computed when processing the command, and can take a long time to generate if you are listing many users or have many groups.

Example

esfadmin listuser user="A*"

Lists all users with names beginning with “A”.

Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


SETOPTIONS

Not currently in use.

Parent topic: esfadmin Sub-commands


SETPASSWORD

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

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

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

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

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

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

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

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

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

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

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


MLDAP ESM Module

The MLDAP ESM Module is the ESM Module that enables LDAP servers to be used as External Security Managers for Enterprise Server.

MLDAP (Micro Focus LDAP) is an interface to multiple LDAP providers. It lets the MLDAP ESM Module communicate with a variety of LDAP directories, such as Microsoft Active Directory. The directory can be located on the same system as Enterprise Server, which is often the case for development workstations. (Windows development systems can use AD/LDS (formerly ADAM), Microsoft's version of Active Directory for applications, for example.) Or the directory can be remote, which is more common in production environments.

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 a 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 the MLDAP ESM Module is invoked by ESF Manager to process a security request, it searches the configured LDAP repository for relevant rules and applies whatever it finds. Like other ESM Modules, it can return a definite result if it finds an applicable rule, or an indefinite result otherwise. (See the discussion of Security Function Return Codes.) Since multiple ESM Modules can be configured, this allows configurations such as user and resource information in separate directories, or the resolution of some requests using LDAP and others using some other ESM.

Version 2 of the MLDAP ESM Module , released with Enterprise Server 2.3 and some hotfixes for 2.2 Update 2, includes a new algorithm for matching resource access control rules with security checks. This new algorithm is used by default. It provides better performance and more intuitive behavior in a number of common cases, and enables new features such as Username Substitution. Because some existing customers with complex, ambiguous security rules might see changes in behavior with the new algorithm, the method used in version 1 of the MLDAP ESM Module is still available and can be selected using a configuration option. See Compatibility Rule Matching for more information.

  • LDAP Client and Server Software
  • The Micro Focus LDAP Schema
  • Resource Access Control
    Describes how rules control access to protected resources.
  • Module Configuration
  • Using All Groups to Which a User Belongs
  • Federation in the MLDAP ESM Module
Parent topic: Securing an Enterprise Server Installation
Related concepts
Username Substitution
Compatibility Rule Matching


LDAP Client and Server Software

The MLDAP ESM Module uses an LDAP client library, also called a provider, to communicate with an LDAP server.

The MLDAP ESM Module uses the Micro Focus LDAP library to provide a common API to LDAP providers. The ESM Module tells MLDAP what LDAP provider library to load and call. Micro Focus does not supply an LDAP provider library of our own. On Windows, the default provider is the one Microsoft includes with the operating system. On Unix, we bundle the OpenLDAP open source client library as the default provider.

You can also configure the ESM Module to use a different provider library by setting the provider option in the Security Manager configuration.

The LDAP server maintains a directory (sometimes called a repository) of security, configuration, and other data. Micro Focus does not supply its own LDAP server, but we do bundle the Microsoft ADAM (Active Directory / Application Mode) server on Windows.

This documentation assumes you already have an LDAP provider library installed on the system where you're using the MLDAP ESM Module, and an LDAP server available on your network. If not, you can contact your operating system vendor or try the free OpenLDAP implementation from http://www.openldap.org.

Parent topic: MLDAP ESM Module
Related concepts
MLDAP ESM Module Custom Configuration Information
Module Configuration
MLDAP ESM Module Custom Configuration Information
Wildcards for Resource, User, and Group Names


The Micro Focus LDAP Schema

LDAP directories are composed of objects with attributes. The objects are arranged hierarchically within special objects called containers; containers can hold both regular objects and other containers. Each object is of a particular class, which defines what attributes that object can have and other information.

The definition of object classes and the hierarchy of containers in an LDAP directory is called a schema. Each LDAP directory has a schema, which can be extended by importing another schema into it. The MLDAP ESM comes with the Micro Focus Schema which can be imported into your LDAP server. It is also possible to adapt an existing schema to replace part of the Micro Focus schema, but that requires advanced LDAP knowledge. The rest of this discussion assumes you are using the standard Micro Focus schema.

All objects have a Distinguished Name or DN, which is a string made up of components in the form type=value, separated by commas. The DN is unique among all the objects in the directory. Objects also have a Common Name or CN, which is a simple string (possibly including spaces). CNs are not unique across the directory, but may be required to be unique within a certain scope, such as within the object's container.

The standard Micro Focus LDAP Schema puts all of its objects in an outer container called the Application Partition. By default this is named:

CN=Micro Focus,CN=Program Data,DC=local

Within the application partition, we define containers for users, user groups, and resources:

CN=Enterprise Server Users,CN=Micro Focus,CN=Program Data,DC=local
CN=Enterprise Server User Groups,CN=Micro Focus,CN=Program Data,DC=local
CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local

The Enterprise Server Users container will hold one object of class microfocus-MFDS-User for each user defined for Enterprise Server. This object class, also defined by the Micro Focus schema, includes the user name (as its CN), password (or a password verifier such as a hash value), user information used within MTO such as an optional operator class, and security information such as expiration date and whether login is allowed.

Note: The MLDAP ESM Module can be configured to use an LDAP class other than microfocus-MFDS-User. For example, if you have existing LDAP users defined using the LDAP class user, you can extend your LDAP schema to add the user attributes defined by Micro Focus to the user class and then configure the ESM module to use it for user definitions. Note, though, that adding new users through the ESM Module (using MFDS or the esfadmin utility) may not work (due to additional object constraints) if you do not use the microfocus-MFDS-User class, in which case you will have to use third-party LDAP or provisioning tools to create new users.

The Enterprise Server User Groups container holds objects of class microfocus-MFDS-Group, which simply contain the name of the group (as CNs) and the list of users who belong to that group. User groups simplify writing resource security rules for multiple users, as rules can be applied to entire groups as well as to users.

Each group member can be either the name of a user, or the group keyword followed by the name of another group. In the latter case, all the members of the named group are included in the group being defined. These "nested groups" can be used to define a hierarchy of groups, for example collecting several groups of developers into a single "ALLDEV" group. They can also be used to create very large groups, when the number of users for a group exceeds the maximum size of a multi-valued attribute supported by your LDAP server.

The Enterprise Server Resources container holds additional containers, one for each resource class. All protected resources (programs, transactions, datasets, etc) belong to a resource class (not to be confused with an LDAP object class), which in effect specifies the namespace for the resource name. That is, you can define resources with the same name, provided they belong to different classes. MTO resources use various class names defined by IBM. Non-MTO resources, such as Enterprise Server configuration definitions in MFDS, use resource class names defined by Micro Focus (using syntax that's not permitted for MTO resource class names, to avoid collisions). Users can also define their own resource classes for performing explicit access checks in applications.

Each resource class is defined as a container in Enterprise Server Resources, with the class name becoming the CN of the class container.

Within each class container are zero or more resource objects, of class microfocus-MFDS-Resource. For these objects, the CN can either be a full resource name, such as a transaction name or a dataset name, or it can be a partially- or fully-wildcarded name, which will match various resource names. This lets you write a single rule to apply to multiple resources. Wildcards are discussed in more detail in the Wildcards topic.

Each resource object also has an attribute named microfocus-MFDS-Resource-ACE, which is a multivalued attribute that holds the 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.) ACLs are discussed in more detail in the Resource Access Control Lists topic.

  • Wildcards for Resource, User, and Group Names
  • Username Substitution
  • Nested Groups
Parent topic: MLDAP ESM Module


Wildcards for Resource, User, and Group Names

The MLDAP ESM Module supports three wildcards:

* | Match zero or more characters, except the period "." (full stop, dot) character. This exception is generally only useful in dataset names, where it indicates that the wildcard applies only to the current DSN qualifier.
** | Match zero or more characters, including the period ".". Usually used only in dataset names, to indicate any number of qualifiers, since the period character does not usually appear in other names.
+ | Match exactly one character, except the period ".". This is not treated as a wildcard by default; it must be enabled in the module configuration using the plus-wildcard option.

Wildcards can appear in two places:

  • In the names of resource objects in the LDAP directory. When a resource object in the directory has a name with a wildcard (sometimes called a generic name), its ACL applies to all the resources with a name that matches that pattern, unless another resource definition with a more-specific name (see Match Rank) exists.
  • In user and group names in an Access Control Entry. Such an entry will apply to all users or groups with names that match the pattern, unless another ACE with a more-specific name (see Match Rank) exists in that ACL.
Parent topic: The Micro Focus LDAP Schema
Related concepts
Match Rank


Username Substitution

Beginning with version 2 of the MLDAP ESM Module (available in Enterprise Server 2.3 and some hotfixes for Enterprise Server 2.2 Update 2), you can also define resource-rule names based on the name of the user who is requesting access. This lets you create generic rules that apply to resources that include the user's name in the resource name. Typically this is used for rules in the DATASET and JESSPOOL classes, to give users access to resources that include their name as a qualifier.

To use this feature:
  • You must be using MLDAP ESM Module version 2 with the new rule-matching algorithm defined. That is the default for Enterprise Server 2.3. For Enterprise Server 2.2 Update 2 Hotfix 7 and later, you must enable the new algorithm by setting Version 1 authentication=no in the [Operation] section of the Security Manager configuration.
  • In the Security Manager configuration area, set Rule substitutions=yes in the [Operation] section.
  • Use the token ${user} in resource access rule names where you would like the requesting user's name to be substituted; for example, USERS.${user}.**. In the ACL for such a rule you can simply use * as the actor name, since the rule will only have effect for resources that contain the user's name.

When determining rule precedence, rules with username substitution rank as high as if the user's name appeared literally in the rule. A rule like USERS.${user}.** will take precedence over one named USERS.*.** when the user's name appears as the second qualifier in the dataset name.

Configuration to enable username substitution

[Operation]
Version 1 authentication=no
Rule substitution=yes

The Version 1 authentication line is not needed (but allowed) in Enterprise Server 2.3 and later.

Dataset rule with username substitution

LDIF syntax for a pair of rules that gives each user access to their own datasets under USERS.**, while denying other users access to them:

dn: CN=USERS.${user}.**,CN=DATASET,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=X
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: DATASET
microfocus-MFDS-Resource-ACE: allow:*:alter
microfocus-MFDS-UID: USERS.${user}.**
description: Allow full access to user's own area

dn: CN=USERS.**,CN=DATASET,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=X
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: DATASET
microfocus-MFDS-Resource-ACE: allow:*:none
microfocus-MFDS-UID: USERS.**
description: Users don't have access to each other's areas

Rule to give users access to their own spool output

LDIF syntax for a rule that gives each user control over their own spool output:

dn: CN=*.${user}.**,CN=JESSPOOL,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=X
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: JESSPOOL
microfocus-MFDS-Resource-ACE: allow:*:control
microfocus-MFDS-UID: *.${user}.**
description: Give each user control over their own spool output

In the JESSPOOL class, resources have the format localnodeid.userid.jobname.jobid.dsnumber.name. This rule matches when the requesting user's name appears as the userid qualifier, and gives that user control authority.

Parent topic: The Micro Focus LDAP Schema
Related concepts
Resource Access Control
MLDAP ESM Module Custom Configuration Information


Nested Groups

Beginning with version 2 of the MLDAP ESM Module (available in Enterprise Server 2.3 and some hotfixes for Enterprise Server 2.2 Update 2), you can specify groups as members of other groups. This nested groups feature lets you add users to groups through a form of inheritance and create large user groups.

No special module configuration is required to use nested groups. To include group A in group B, simply add group A to the list of members for group B. In this case group B is known as a supergroup of group A. Users who belong to group A will now also belong to group B.

Nested groups are generally most useful when All-Groups Mode is enabled, but do not require it.

Applications

Nested groups may be useful for various purposes:

  • Large groups. In the Micro Focus LDAP Schema, user groups are implemented as LDAP objects with membership information stored in the multivalued microfocus-MFDS-Group-Member attribute. LDAP servers generally have restrictions on how large an attribute can be, which limits the number of members that a group can have. Nested groups can be used to create a group with a large number of members. For example, to create an ALLUSERS group with thousands of users, you might create a USERSA group with all the users whose user IDs begin with "A", a USERSB group, and so on; then make the USERSA, USERSB, ... groups members of ALLUSERS. USERSA and its sibling groups may never be used for any other purpose (for example, there may not be any ACEs that assign permissions to those groups); they exist just to let ALLUSERS contain all the user accounts.
  • Group hierarchies. Sometimes user groups conceptually form a hierarchy. For example, there might be groups for individual project areas (UI, ENGINE, etc), all of which are part of a larger DEVEL group. Nested groups lets you represent this arrangement by including the more-specific groups in the larger group.
  • Simplified group and permission management. Nested groups can reduce the number of groups a user needs to be explicitly added to, in order to correctly represent that user's position in the organization and assign the correct permissions. That can make it simpler to update group membership when adding and removing users.

Limitations

Not all ESF Administration features currently work correctly with nested groups. If you use nested groups, Micro Focus recommends administering them with the esfadmin command's ADDMEMBER and DELMEMBER sub-commands, or with LDAP tools operating directly on the LDAP repository, rather than using the MFDS graphical user interface. The LISTREFERENCES sub-command (and ESF Admin API function) does not currently show supergroup membership; that also means that the Referential Integrity Sample User Exit does not recognize that users belong to supergroups.

Group membership changes, including changes in how groups are nested, are recognized when a user signs on to a region for the first time after that region is started. You can also instruct the region to update its information about group membership by sending it an ESF update request using the MFDS administration user interface or the esfupdate command-line utility.

Nesting a group using esfadmin

Assume Alice belongs to the PROJ1 group. We can add PROJ1 to the DEV group using the esfadmin command:

esfadmin options ADDMEMBER GROUP=DEV MEMBER="PROJ1 group"

Now Alice will belong to both PROJ1 and DEV.

Nesting a group using LDIF

The following LDIF fragment creates the AUDIT and FINANCE groups, and makes AUDIT part of FINANCE:

dn: cn=AUDIT,CN=Enterprise Server User Groups,CN=Micro Focus,CN=Program Data,DC=X
changetype: add
adminDisplayName: Audit group
objectClass: microfocus-MFDS-Group
microfocus-MFDS-UID: AUDIT
description: ES auditors group

dn: cn=FINANCE,CN=Enterprise Server User Groups,CN=Micro Focus,CN=Program Data,DC=X
changetype: add
adminDisplayName: Finance group
objectClass: microfocus-MFDS-Group
microfocus-MFDS-UID: FINANCE
description: ES finance group
microfocus-MFDS-Group-Member: AUDIT group
Parent topic: The Micro Focus LDAP Schema


Resource Access Control

The MLDAP ESM Module lets you control access to resources managed by Enterprise Server, by specifying rules in the LDAP repository. A rule associates one or more resources with an Access Control List (ACL), and the ACL defines what type of access various users and groups have to the resource. When an application tries to use a resource, Enterprise Server asks ESF whether the request (a particular action, such as updating, applied to a particular resource, such as a dataset) should be allowed. If ESF is configured to use the MLDAP ESM Module, the module will find the most-appropriate resource access rule and apply its ACL to decide whether the request is permitted.

  • Matching Rules and ACEs
  • Resource Access Control Lists
Parent topic: MLDAP ESM Module


Matching Rules and ACEs

When the MLDAP ESM Module receives a request to authorize a user's access to some resource, it checks the rules stored in the LDAP repository to make its decision.

Access control rules in the LDAP repository

Enterprise Server resources are grouped into categories called classes. Each class exists as an LDAP container in the repository. Within the class containers are resource rules. Rules are named for the resources they apply to, and their names can include wildcards, so a rule named "*" (or "**" for datasets) applies to all resources of that class.

Because a class can have multiple rules that match the name of the resource being accessed, the MLDAP ESM Module applies algorithms to determine which rule will determine the result of a particular request. Generally speaking, a more specific rule that matches the request should take precedence. So, for example, if a user attempts to submit the CICS transaction ACCT, and there is a rule named "ACCT" and another rule named "A*", the "ACCT" rule should override the "A*" rule.

Rule processing in MLDAP ESM Module versions 1 and 2

Version 1 of the MLDAP ESM Module, included in all products prior to Enterprise Server 2.3 (except for some hotfix releases for 2.2 Update 2), used a complex algorithm to retrieve resource rule data from the LDAP server and evaluate it using another algorithm called "Match Rank". The Match Rank algorithm was also used to decide which part of an ACL (an Access Control Entry or ACE) applied to the user making the request. See Compatibility Rule Matching for more information on the process used in version 1 of the module. Enterprise Server 2.3 introduced MLDAP ESM Module version 2, with a new, simplified process for matching resource access requests to rules and matching ACEs to users. This new processing algorithm provides more predictable and understandable behavior when resource rules are ambiguous, and also offers better performance in some cases.

For Enterprise Server 2.3 the new algorithm is the default. (In Enterprise Server 2.2 Update 2 hotfixes that include MLDAP ESM Module version 2, the old algorithm is still the default, to avoid changing behavior in a hotfix release.) Most customers will want to use the new algorithm for its better behavior and performance, and possibly for new features that require it. In rare cases, however, customers with complex, ambiguous resource access control rules might notice different results for some authorization queries using the new algorithm. The MLDAP ESM Module can be configured to use the old algorithm by specifying the Version 1 authentication configuration setting.

Example: Different precedence order between versions 1 and 2

Suppose you have the following two dataset access control rules, with corresponding ACLs.

DEV.** | allow:alice:read
**.ALICE.* | allow:alice:update

The first rule is meant to give Alice read access to all datasets under the DEV top-level qualifier, and update access to all datasets with ALICE as the final qualifier. What happens if Alice tries to update the dataset DEV.PROJ1.ALICE.NOTES?

Of the two rules, the second (**.ALICE.*) matches that dataset name better, because it matches more literal characters. Under the version 1 algorithm, however, the module will apply the first rule, because it will find it first while searching for applicable rules. That means Alice will not have update access to the dataset. With the version 2 algorithm, the module finds all the rules that might apply, then processes them in the order of closest to furthest match. So when the version 2 algorithm is used, the second rule will apply, and Alice will be granted update access.

  • Compatibility Rule Matching
    Describes the rule-matching process for version 1 of the MLDAP ESM Module.
Parent topic: Resource Access Control


Compatibility Rule Matching

Because the names of resource access control rules and ACE actors can include wildcard sequences, the MLDAP ESM Module must examine all the matching rules and ACEs and decide which one best applies to a request. Version 2 of the Module, introduced in Enterprise Server 2.3, provides a new, simpler mechanism for this process, which tries to find the intuitively best match, the one that is closest to the resource, user, or group name being matched. This new algorithm is used by default (except in hotfix releases of Enterprise Server 2.2 Update 2 that include a version-2 MLDAP ESM Module).

Older versions of the MLDAP ESM Module used a more complex algorithm. In rare cases, a complicated, ambiguous set of resource rule definitions might have different results with the new algorithm, so the older mechanism is still supported and can be enabled in the Security Manager configuration using the Version 1 authentication option.

The topics below explain the older matching mechanism in more detail.

  • Resource Rules, Search Order, and Precedence
  • Match Rank
Parent topic: Matching Rules and ACEs


Resource Rules, Search Order, and Precedence

Note: The following discussion applies only when Compatibility Rule Matching is enabled. In version 2 of the MLDAP ESM Module, the default behavior is to use the new rule matching algorithm, which retrieves all applicable rules from the LDAP repository and checks them in the order of strongest to weakest match.

Since the MLDAP ESM Module supports wildcards in resource rule names, it is possible that several rules may apply to a single resource access query. The module has to communicate with the LDAP server to retrieve rules, and the server has to search for rules that match the search string sent by the module. That makes it prohibitively expensive, generally speaking, for the module to simply search for all the rules that might apply to a request.

To provide adequate performance, the MLDAP ESM Module tries to answer an access query (AUTH or XAUTH call) with as few LDAP searches as possible, using these principles:

  1. Access is determined by the first defining rule that the module finds and processes. A defining rule is a rule that can answer the access query. It:
    • Applies to the right class of resource.
    • Has a name that matches the resource name, either literally or as a wildcard pattern match.
    • Has an Access Control List that includes at least one entry that applies to the specified user (including user group membership), and that allows or denies the level (for AUTH) or type (for XAUTH) of access requested. Note that denial may be implicit; see Permissions.
  2. The module first searches for a rule with the same literal name as the resource it's looking for. If it gets a request for access to a transaction named "TRAN", for example, it will first look for a rule named "TRAN".
  3. If no such rule is found, or it is not a defining rule for the user making the request (that is, it doesn't have an ACE that applies to the current user), the module performs a longest prefix search for matching wildcarded rules:
    1. First, it will search for the resource name followed by a literal "*" character - that is, for a wildcard rule that begins with a prefix that matches the sought name literally.
    2. Then it replaces the last character of the prefix with a "*" character (so "NAME*" becomes "NAM*") and performs another search. This process will continue until it gets to "*" or it finds a defining rule.
    3. If any of these searches returns multiple rules, they will be processed in match rank order. For example, if the module is trying to authorize access to "NAME" and searches for "N*", it might find rules named "N*" and "N*E". The latter would be processed before the former, because it has higher rank (is a closer match).

One consequence of this approach that may not be immediately obvious is that a short prefix followed by a wildcard will take effect before a wildcard followed by a long (or indeed any) suffix. For example, when searching for "NAME", a rule named "N*" would be found and used before one named "*AME".

Parent topic: Compatibility Rule Matching
Related concepts
Wildcards for Resource, User, and Group Names
Resource Access Control Lists
Access Levels and Permissions
Match Rank


Match Rank

Note: The following discussion applies only when Compatibility Rule Matching is enabled. In version 2 of the MLDAP ESM Module, the default behavior is to use the new rule matching algorithm, which retrieves all applicable rules from the LDAP repository and checks them in the order of strongest to weakest match. In the new algorithm, matching is based on how many characters must be substituted for wildcard sequences to match the requested name.

Both rules and ACEs are prioritized by match rank, which is a measure of how closely the wildcarded string matches the literal string that the ESM Module is searching for (either the resource name or the user/group name). Match rank is an integer value; the higher the value, the closer the match, and the higher the priority of the matched item.

Match rank only applies to matching patterns - patterns that do not match are skipped and never ranked.

Match rank is computed from the number of literal characters and the number of distinct wildcard sequences in the pattern. A distinct wildcard sequence is any number of adjacent wildcard characters, so "*" and "**" both count as one sequence. The rank is also normalized by the length of the name being matched to the pattern; this lets the ESM Module compare rank for user ACEs and group ACEs even if the user name and the group name are different lengths (as they usually are). The formula is:

R = 512 x L / N - W + 1

where R is the rank value, L is the number of literal characters in the pattern, N is the length of the name being matched, and W is the number of wildcard sequences. So "pat" would outrank "p**t**", which would outrank "p*", which would outrank "*a*", which would outrank "*".

When the MLDAP ESM Module gets back multiple rules for a wildcard search, it sorts them by match rank and processes them in priority order. (Processing stops when the query can be answered - see Resource Rules for details.) When the module is processing the ACEs in an ACL, it lets higher-ranked ACEs (ones that better match the user's or group's name) override lower ones.

For example, if the module is asked to authorize access to a resource named "RESOURCE", and has found rules named "R*" and "R*E", the latter rule will be processed first, because it has higher rank. If it is authorizing for user "USER" and finds ACEs "allow:U*:read" and "deny:*:read", the former would take effect because of its higher rank.

When two rules or ACEs have the same rank, their relative priority is undefined, and either may take effect; so avoid creating conflicting rules and ACEs with the same rank.

Parent topic: Compatibility Rule Matching
Related concepts
Resource Rules, Search Order, and Precedence


Resource Access Control Lists

Each protected resource has one or more ACLs associated with it, either specifically for that resource, or through a wildcard resource object that matches the resource's name. Each ACL, in turn, has one or more ACEs. 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.

An ACE (Access Control Entry) is an entry in an ACL (Access Control List), which can have zero or more entries. In our schema, an ACL is the multi-valued attribute "microfocus-MFDS-Resource-ACE"; each value is a separate ACE. (Don't confuse these ACEs with the ACEEs used by ESF - they're completely different things.)

The general ACE format is:

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) 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

MTO resources (transactions, programs, datasets, etc) will typically only have one action per ACE. With the mainframe-style permissions used in MTO, there's no point in specifying multiple actions, since only the highest action applies. For the "extended" or "independent" permissions used for MFDS resources (server definitions and administrative controls) it's often useful to specify multiple actions in an ACE.

  • Users and Groups
  • "Use all groups" Mode
  • Access Levels and Permissions
  • ACE Precedence
  • Processing ACLs
Parent topic: Resource Access Control


Users and Groups

An ACE applies to the current user if the actor string matches the user's name (including with wildcards, if any) or the name of the user's signon group, or if all-groups mode is enabled, the name of any group the user belongs to.

The user's signon group is normally the user's default group; the MLDAP ESM Module assigns this group name from the value of the LDAP attribute microfocus-MFDS-User-DefaultGroup. A different group can optionally be supplied in the VERIFY call that authenticates the user; if the user is a member of that group, they will use that group as their signon group for that session. Usually, the signon facility (such as the CICS CESN transaction) provides a way for users to enter an optional group name.

As of MLDAP ESM Module 1.6.0, actor names in ACEs are case-insensitive, so an ACE like allow:sysad:read will apply to the SYSAD user.

Parent topic: Resource Access Control Lists


"Use all groups" Mode

Normally, only the user's signon group is used when checking for group permissions for a resource, for performance reasons. If the option "Use all groups" is enabled in MFDS for the current Enterprise Server server, however, users will automatically have the permissions of all the groups they currently belong to. (In this case the signon group is unimportant.) This is equivalent to the "List-of-groups processing" available as an option in some mainframe security facilities, or the usual behavior of UNIX and Microsoft Windows.

Note: Use-all-groups mode consumes additional resources (notably CAS shared memory, when running under CAS) for the list of group names and the per-user group membership information. Also, it requires additional LDAP searching and processing during Verify operations, and additional processing during Auth and XAuth operations. (It is especially expensive when operating on ACLs that include wildcarded group names, such as "allow:x* group:update", which would apply to all groups with names beginning with "x".)

When use-all-groups mode is in effect, there is a configurable limit to the number of user groups. (The limit applies to the number of groups that include users who have signed on since the region was started, so groups that are defined but not used don't count against it.) See [Operation] section.

If you have stacked multiple MLDAP ESM Modules in your security configuration, there are special considerations for use-all-groups mode. See the sections on Federation and maxgroups for more information.

Parent topic: Resource Access Control Lists
Related concepts
MLDAP ESM Module Custom Configuration Information
Access Levels and Permissions
Wildcards for Resource, User, and Group Names
Federation in the MLDAP ESM Module


Access Levels and Permissions

There are two ESF API Auth functions: AUTH and XAUTH. AUTH is used by MTO; XAUTH currently by MFDS, and probably by other non-MTO facilities (such as Web Services) in the future.

AUTH implements mainframe-style permissions, where a user is granted a permission level that includes all the "lower" permissions (write access implies read access and so forth). XAUTH implements more modern discretionary access controls (DACs) with up to 32 independent permission bits. The Enterprise Server MTO subsystems (CICS, etc) use AUTH and mainframe permissions; MFDS uses XAUTH and independent (aka "extended") permissions.

Resources are typically defined for MTO or for MFDS, and not for both, so the two kinds of permissions do not normally apply to the same object. If they do, for some reason, an allow ACE that specifies the desired MFDS permissions will also grant the highest specified access level for mainframe-style permissions. For example, "allow:user:read,update" grants read and update access under MFDS and update-level access under MTO.

Mainframe-Style Access Levels (MTO)

Mainframe-style permissions are a strict hierarchy of six levels:

  1. no access
  2. execute
  3. read-only (plus execute for programs)
  4. update (adds ability to write)
  5. control (adds the ability to delete, etc)
  6. alter (can do anything, including changing permissions)

For mainframe-style permissions, the "add" and "delete" tokens in an ACE are synonyms for "update". The "none" token is a synonym for the lowest level (no access), when used in an allow rule; in a deny rule, it has no effect except to override any lower-ranked deny rule. The "all" token is a synonym for the highest level (currently "alter").

So rather than a set of orthogonal permissions, as in most DAC systems, we have a current permission level which can be increased by allow rules.

If we encounter a deny rule for the access level we're looking for or a lower one, we deny the request. If the user wants update access, for example, they're not affected by a deny for control, but they are affected by a deny for read, because update requires read.

Independent Permissions (MFDS)

Independent (or extended) permissions are separate from one another; a user can have write access but not read access to a resource under the independent-permissions model. Independent permissions are used if the ESF caller uses the XAUTH request. Currently only MFDS uses XAUTH.

With independent permissions, a user has a set of permissions for any given resource that can include some, all, or none of the following:

  • execute (used for starting and stopping servers, etc)
  • read
  • update (change, but not add or delete)
  • add
  • delete
  • control (not currently used by MFDS)
  • alter (not currently used by MFDS)

Allow ACEs add the specified permissions to the set; deny ACEs remove the specified permission. (If allow and deny ACEs of equal rank specify the same permission for a user, the deny overrides the allow, and the permission is not granted.)

For independent permissions, the "all" token corresponds to setting all of the permissions (ie it is a synonym for "execute, read, update, add, delete, control, alter"), and the "none" token sets none of the permissions.

Parent topic: Resource Access Control Lists
Related concepts
Match Rank


ACE Precedence

ACEs can refer to users or groups. They can specify an exact name or a pattern with wildcards. They can allow or deny an access level or set of permissions.

This flexibility means that even within the single ACL belonging to the defining rule that the MLDAP Module uses to determine whether the requested access is allowed (or what the user's effective access rights are, for a permissions query), there may be conflicting ACEs. The module applies these rules to make its access decision:

  • Higher-ranked ACEs override lower-ranked ones.
    • In MLDAP ESM Module version 2, ACE ranking is determined by how many characters from the user or group name replace wildcard characters in the ACE actor name. For user Bob, an ACE that refers to BOB outranks one that refers to B*, which outranks one that simply specifies *.
    • In MLDAP ESM Module version 1, or if compatibility rule matching is enabled for version 2, the Match Rank algorithm is used to determine how ACEs are ranked.
  • Within the same rank, user ACEs override group ACEs.
  • For ACEs of the same rank for the same actor (user or group), deny ACEs override allow ACEs.
  • For MTO resources:
    • For allow ACEs of the same rank and actor, the highest specified access level applies.
    • For deny ACEs of the same rank and actor, the lowest specified access level applies (because higher levels implicitly include lower ones; so if read access is denied, update access must also be denied).
  • For MFDS resources:
    • Allow ACEs of the same rank and actor are combined (set union).
    • Deny ACEs of the same rank and actor are combined.
Parent topic: Resource Access Control Lists
Related concepts
Users and Groups
Wildcards for Resource, User, and Group Names
Resource Rules, Search Order, and Precedence
Match Rank


Processing ACLs

To process an ACL, the module iterates through the entries (ACEs) in the list. Note that the LDAP server may return an ACL's entries in any order, so do not assume the order of entries has any effect on the outcome. For each entry:

    • if this entry applies to this user
      • if this is an allow rule
        • if this is a higher-ranked rule than any we have processed so far
          • reset the current allowed-access level and permission set for the user
        • for each action specified in the entry
          • if this specifies a higher level of access
            • update the user's allowed-access level
          • add the specified action to the user's allowed-permissions set
      • else (this is a deny rule)
        • if this is a higher-ranked rule than any we have processed so far
          • reset the current denied-access level and permission set for the user
        • for each action specified in the entry
          • if this specifies a lower level of access
            • update the user's denied-access level
          • add the specified action to the user's denied-permissions set
    • if this entry applies to an applicable group
      • do the same as above, but updating group-allow and group-deny variables

After processing all of the ACL:

  • if no applicable entries were found, continue on with the next rule
  • if this is an AUTH (MTO resource, mainframe-style access levels) request
    • if group entries were found but no user entries, use the group entries
    • if user entries were found but no group entries, or the user entries are at the same or higher rank than the group entries, use the user entries
    • if this is an access request
      • if there are deny entries at the same or higher rank than the allow entries, and the deny level is less than or equal to the requested level
        • deny the request
      • else if the requested level is greater than the allowed level
        • deny the request
      • else
        • allow the request
    • else (this is a permissions query)
      • if there are deny entries at the same or higher rank than the allow entries
        • reduce the allowed level to one below the lowest denied level (eg if update is denied, reduce the allowed level to read)
      • return the allowed level
  • else (this is an XAUTH, MFDS resource, permissions-set request)
    • compare the ranks of user-allow, user-deny, group-allow, and group-deny permissions
    • the highest of the four determines whether user rules outrank group rules, or vice versa (if user and group are equal rank, user wins)
    • compute the final set of permissions as
      • add lower-ranked allowed permissions
      • remove lower-ranked denied permissions
      • add higher-ranked allowed permissions
      • remove higher-ranked denied permissions
    • if this is an access request
      • if the requested permissions are all in the result set
        • allow the request
      • else
        • deny the request
      • else (this is a permissions query)
        • return the result set

In other words, access-level requests first decide whether user or group rules should apply (based on rank), then determine the level that results from those rules, then return the appropriate result based on that level.

Permissions-set requests start with the lower-ranked rules, then allow the higher-ranked rules to override them, to determine the final effective set of permissions.

Parent topic: Resource Access Control Lists
Related concepts
Users and Groups
Resource Rules, Search Order, and Precedence


Module Configuration

The MLDAP ESM Module has a number of configurable parameters. Its configuration is administered with the Micro Focus Directory Server (MFDS). Currently, ESM Module configuration is found in the Options section, in the Security Managers tab under the Security... tab, but this might change in future releases.

You can create multiple "Security Manager" objects in MFDS using the MLDAP ESM Module, in order to use the module with different configurations for different Enterprise Server servers or for MFDS itself.

To select the MLDAP ESM Module for a Security Manager, set the Module field to mldap_esm.

  • MLDAP ESM Module Configuration Fields
Parent topic: MLDAP ESM Module


MLDAP ESM Module Configuration Fields

The other fields of the Security Manager screen are used by the MLDAP ESM Module as follows:

Connection Path
This is the location of the LDAP server, specified as a hostname or IP address, optionally followed by a colon and a port. The default is localhost:389 (389 is the well-known port for LDAP).
Authorized ID
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 needs to have modify access to user definitions if you wish to support letting users change their passwords from Enterprise Server (for example from the CICS signon screen). The default is CN=MFReader,CN=ADAM Users,CN=Micro Focus,CN=Program Data,DC=local (though the last three components can be changed by setting the base DN; see below), which is the user object created for this purpose in the sample configuration.
Password
The password used to bind to the LDAP server. The default is the password used in the sample configuration.
Enabled
If this box is unchecked, ESF Manager will not load, initialize, or pass requests to this ESM Module. In a future release it will be possible to dynamically enable and disable ESM Modules while the region is running.
Cache limit
This parameter is currently ignored by the ESM Module.
Cache TTL
This parameter is currently ignored by the ESM Module.
  • MLDAP ESM Module Custom Configuration Information
Parent topic: Module Configuration


MLDAP ESM Module Custom Configuration Information

The MLDAP ESM 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 in the form name=value.

Here are the various configuration sections, and the options that can be set in each section.

[LDAP] section

provider=module
The name of the dynamically-loadable module containing the LDAP client functions. It should be a DLL (Windows) or shared object (Unix), exporting the standard LDAP C API functions. On UNIX, if module does not include a file extension, the standard Micro Focus file extension for that platform (eg "_t.so.2") will be appended (so the same configuration can be used on platforms with different naming conventions). On Windows this defaults to wldap32.dll, the Microsoft LDAP client. On UNIX, the default is openldap, which is the Micro Focus port of the OpenLDAP client library.
Example:
[LDAP]
 provider=libldap.a
will instruct the ESM Module to use the provider library libldap.a, the LDAP client available from IBM for AIX.
version=2 | 3
Set the LDAP protocol version. The default is 3. Normally this does not need to be changed, since if either the client or server does not support version 3, they should automatically fall back to version 2.
base=DN
Set the base container for Enterprise Server security information in the LDAP server. The default is CN=Micro Focus,CN=Program Data,DC=local, which is the container used in the sample configuration. The value should be the common part of the DNs of the Enterprise Server Users, Enterprise Server User Groups, and Enterprise Server Resources containers.

Note:

If your user, group, and resource containers are in separate branches of your LDAP repository, you can set Base to an empty string and use full DNs for user container, group container, and resource container.
user class=LDAP class name
Set the name of the LDAP object class used to hold user information. The default is microfocus-MFDS-User, but installations with existing user definitions in an LDAP repository might want to extend those definitions with the Micro Focus MTO user attributes and use them instead.
user container=partial DN
Set the name of the LDAP container that holds Enterprise Server user objects. The value should be one or more LDAP DN components; the LDAP "base" DN (see Base above) will be appended to the value to create the full DN of the user container. The default is CN=Enterprise Server Users.
user ID attribute=name
Set the name of the LDAP attribute that holds the MTO user name in an Enterprise Server user object. This is useful if your LDAP schema already uses the default "cn" (Common Name) attribute for some other purpose. Note that if this option is set to a non-default value, the sample LDAP schema and data files will have to be edited in order to create compatible data in the LDAP repository. Attribute names are case-insensitive. The default is CN.
group class=LDAP class name
Set the name of the LDAP object class used to hold group information. The default is microfocus-MFDS-Group.
group container=partial DN
Set the name of the LDAP container that holds Enterprise Server group objects. The default is CN=Enterprise Server User Groups.
resource class=LDAP class name
Set the name of the LDAP object class used to hold resource access rule information. The default is microfocus-MFDS-Resource.
resource container=partial DN
Set the name of the LDAP container that holds Enterprise Server resource access rule objects. The default is CN=Enterprise Server Resources.
bind=simple | negotiate | es-user
Set the method for binding to the LDAP server:
  • The simple method sends the LDAP credentials in plain text. If you have the ESM Module configured to use a privileged LDAP account (for example, if it has authority to set user attributes, in order to support user password-change requests), and the network connection between the module and the LDAP server is not secure, use one of the other methods. With this method, the "Authorized ID" in the Security Manager configuration should be an LDAP distinguished name.
  • The negotiate method lets the ESM Module and the LDAP server negotiate the most secure method to use. With most LDAP servers this should prevent the LDAP credentials from being sent in the clear. With this method, the "Authorized ID" in the Security Manager configuration depends on the LDAP server; for Active Directory, it should be a Windows username, optionally prefixed with a domain name followed by a backslash (domain\user).
  • The es-user method is only supported on Windows, and only when connecting to Active Directory. It tells the module to bind to LDAP using the user account of the current process (ES/MTO or MFDS). The credentials are not sent in the clear. With this method, the "Authorized ID" and "Password" fields in the Security Manager configuration are ignored.

The default is simple.

search scope=child | tree
Set the scope for LDAP searches. child will search only the first level within the specified user, group, and resource containers. tree will search the entire LDAP hierarchy below the container. Using tree can significantly impact performance, but is useful for directories that organize users or other LDAP records into separate containers.

onelevel and one-level (the technical LDAP term for this scope) are synonyms for child. subtree is a synonym for tree.

The default is child.

referrals=yes | no | default
Enable or disable LDAP referrals. LDAP referrals let one LDAP server pass a query along to another server. Usually referrals do not need to be enabled, and in some cases enabling referrals may cause servers to reject certain queries. For example, Active Directory will reject subtree queries (see search scope above) if referrals are enabled.

If this is set to default (or not set at all), the MLDAP ESM Module leaves the LDAP provider's referrals setting unchanged, and the behavior depends on the provider and server.

The default is default, for compatibility with earlier versions of the MLDAP ESM Module, unless you have search scope=tree also configured, in which case the default is no.

timeout=seconds
Set the timeout for lengthy LDAP operations. This affects LDAP searches; depending on the LDAP provider, it may also affect binding or other operations. If this option is not configured or the value is 0, the provider's default timeout is used.
connect timeout=seconds
Set the timeout for LDAP connection attempts. This affects only the first stage of connecting to the LDAP server: opening the TCP conversation. In most cases, this will either succeed or fail quickly (the server will either accept or reject the connection attempt), so this timeout usually only comes into play when network problems prevent reaching the server host system, or the server host system is down. If this option is not configured or the value is 0, the default is the value of the timeout option, if set; or the LDAP provider's default connection timeout if not.
retry attempts=number
If the LDAP server is unavailable, retry the connection this many times. The amount of time the module waits between attempts can be set using the retry interval option. The default is not to retry (if the initial connection attempt fails, the module returns an error immediately). Note that ESF initialization, the thread invoking ESF, and any processing that depends on security in any other threads will be blocked until the connection succeeds or the module returns an error to ESF.
retry interval=seconds
The number of seconds to wait between attempts to contact the LDAP server. If this value is not set, the module uses exponential backoff: it waits one second before the first retry attempt, then two seconds before the next, doubling the time between each attempt. So the total wait time (not including any time taken by the connection attempts themselves) will be 2^N - 1 seconds, where N is the total number of attempts (including the first). If retry attempts is set to 5, it will take the module at least 31 seconds to report failure. This value can be set to 0 to have the module try again as soon as each attempt fails (no wait).

[Operation] section

maxgroups=number
Set the maximum number of user groups supported in Use-all-groups mode. This must be at least as large as the number of groups that include any user who will sign on to the region. The default is 64; the maximum value is 9999. Increasing this value will consume more shared memory and increase processing time for authorization requests, so we recommend keeping it close to the actual number of user groups you have defined. It has no effect when the "Use all groups" option is not enabled.
Note: If you have multiple MLDAP ESMs stacked in a security configuration, they must have the same setting for maxgroups, unless Federation is explicitly disabled. This requirement is enforced by the module; you will get a warning if your configuration specifies different maxgroups settings for different instances of the MLDAP ESM Module.
signon attempts=number
Set the maximum number of consecutive failed sign-on ( Verify) attempts before a user account is automatically disabled. If number is set to an integer greater than 0, then after that many attempts to sign a user on with incorrect passwords, the account is disabled. (Successfully signing a user on with the correct password resets the count.) The default is 0, which disables this feature.
plus-wildcard=yes | no
If this is set to yes, the plus (+) character is interpreted as a wildcard when it appears in a resource rule name. It functions like the * and ** wildcards, except that it always matches exactly one character.

The default is no.

set login count=yes | no
If the user class includes the microfocus-MFDS-User-LoginAttempts attribute, and this option is set to yes (the default), the MLDAP ESM Module will attempt to keep track of login attempts by updating this attribute. It will be set to an integer value which is incremented for each failed login attempt and reset to zero when the user logs in successfully. If the ESM Module does not have permission to update the user object, this setting has no effect.
set login time=yes | no
If the user class includes the microfocus-MFDS-User-LastLoginTime attribute, and this option is set to yes (the default), the MLDAP ESM Module will attempt to set it to the current UTC time when the user logs in successfully. If the ESM Module does not have permission to update the user object, this setting has no effect.
version 1 authentication=yes | no
If this option is set to yes (the default is no), the Compatibility Rule Matching algorithm will be used.
rule substitutions=yes | no
Set this to yes to enable the use of the ${user} token (which is replaced with the userid of the user making the access request) in resource access control rules. See Username Substitution for more information. Compatibility rule matching must not be enabled.

[Passwords] section

expiration=number
Set the default password expiration interval, in days. It only applies if MF-hash verify mode (ie, Micro Focus password hashes) is being used. (This is the default, but many organizations use bind verify mode, in which case password expiration has to be managed by your LDAP server.) If a user changes their password, and their account is configured with a password expiration date (the microfocus-MFDS-User-Pwd-ExpirationDate attribute), and that date is in the past or less than this many days in the future, then it will be changed to this many days in the future. The default is 90 (days). The microfocus-MFDS-User-Pwd-ExpirationDate attribute must be set to a string of digits representing the four-digit year, the two-digit month, and the two-digit day of the day the password expires (yyyymmdd). Anything following the day is ignored. The standard "UTC Coded Time" format used by many LDAP clients and servers works. You can set an initial password expiration date using a regular LDAP client, or using the esfadmin utility with the ALTUSER command and the PASSEXP attribute.

Example:

esfadmin -uADMIN -pADMIN -U"cn=..." -Pxxx altuser user=SYSAD
passexp=20091231

will set the password expiration date for the user SYSAD to the last day of 2009.

expiration-check=setting
Enables a heuristic that attempts to determine if a user bind was rejected by the LDAP server because the user's password was expired. If this set to "1" or a string beginning with "y", and bind-mode verification is enabled (see the [Verify] section), and a password expiration interval is configured, then when a user's bind request is rejected, the module will check to see if their password expiration date has passed. If so, it will return an error code indicating the password is expired, rather than a generic verify-failed error code.
history=number
Remember number previous password hashes for each user; when users try to change their passwords, if the new password matches one of the stored hashes, reject the request. This option has no effect if the module configuration does not let the module update the user's attributes. The default is 0, ie no password history is kept.
minimum length=number
Require that new passwords be at least number characters long. (Note that while ESF itself supports long passwords, MSS is currently limited to a maximum of 8 characters, so use caution when setting this value.) If you are using a password type other than "MF", you may also be able to configure this and other password requirements in your LDAP server or OS security policy.
maximum length=number
Require that new passwords be no more than number characters long. (Note that while ESF itself supports long passwords, MSS is currently limited to a maximum of 8 characters, so use caution when setting this value.) If you are using a password type other than "MF", you may also be able to configure this and other password requirements in your LDAP server or OS security policy.
required=list of classes
Require new passwords to include at least one character from each of the listed classes. The supported classes are alphabetic, mixed-case, numeric, and punctuation. Class names should be separated by whitespace and/or commas.

Example:

[Passwords]
required=alphabetic, numeric

will cause password changes to fail if the new password does not include at least one letter and one digit.

complexity=number
Require new passwords to include at least one character from number + 1 character classes. Upper and lower case are counted separately, so for example complexity=1 would be satisfied by a mixed-case password, or a password with lower-case letters and digits, or digits and punctuation characters, etc. Characters that are not (ASCII) letters, digits, or punctuation are counted as another character class, so there are five classes (upper, lower, digit, punctuation, and other) in all.

The various password restriction options can be used in combination. For example:

[Passwords]
 minimum length=6
 required=mixed-case
 complexity=2

would enforce passwords of at least 6 characters, with both upper- and lower-case letters and at least one non-letter character.

[Passtoken] section

default=none | self
Set the default passtoken creation and use privileges. Normally, whether a user can create or use ESF Passtokens with this ESM Module is controlled by per-user attributes. If those attributes are not set, they default to none, which means by default users can neither create passtokens nor be signed on using them. Setting this value to self changes the default behavior to allowing the creation and use of self-only passtokens.
secret=string
Set 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
Set 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
Set 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).

[Verify] section

mode=MF-hash | bind
Determine how user credentials (username and password) are verified:
  • The MF-hash method retrieves the value of the microfocus-MFDS-User-Pwd attribute, which contains a verifier (a salted cryptographic hash) for the password. It computes the equivalent hash of the supplied password, and verifies that they match. With this method, the passwords used for verifying users under ESF are private to ESF, and not associated with the operating system or LDAP server.
  • The bind method uses the LDAP server itself to verify the user's credentials, by using them to bind to the server. With this method, the user's password for ESF will be the same as for the LDAP server (which will be the same as for logging into the OS itself, if the OS is using LDAP authentication). However, this method may be somewhat slower and consume more resources.

Other modes may be supported in the future, such as testing other types of password hashes. The default is MF-hash.

password type=MF | AD | MD5 | plain | compatible
Controls how passwords are set in LDAP when a new password is supplied as part of a Verify operation:
  • MF creates a secure verifier (a salted cryptographic hash) of the password, and sets it as the value of the microfocus-MFDS-User-Pwd attribute. This is suitable if you are using the microfocus-MFDS-User class for your Enterprise Server users. It corresponds to the MF-hash password-verification method described above.
  • AD sets the attribute unicodePwd to the value of the supplied password, in quotes. This is a special operation for Microsoft Active Directory (and ADAM) which is equivalent to setting a user's password using the Windows APIs. (Active Directory will create and store a secure hash of the password.) This is suitable if you are using a Microsoft-supplied class for your Enterprise Server users. It corresponds to the bind password-verification method described above, if you are using Active Directory.
  • MD5 computes the MD5 hash of the password and sets it as the value of the userPassword attribute, using the syntax specified by RFC 2307 , which is not standard but is widely supported by LDAP servers. It corresponds to the bind password-verification method if you are using an LDAP server which supports this password type, such as OpenLDAP.
  • plain sets the userPassword attribute in plaintext. It should normally only be used for development purposes, since it is not secure with most LDAP servers. Note that there is an option in Active Directory (which is enabled by default in ADAM) that makes userPassword an "alias" for unicodePwd; if that option is enabled, this method can be used to set passwords in Active Directory or ADAM.
  • The compatible setting first tries to set unicodePwd using the Microsoft syntax, then tries to set userPassword using the MD5 method. This will usually work when the ESM Module is configured to use the bind verification method: if the LDAP server is Active Directory, the unicodePwd attribute setting will work, and if another LDAP server is being used, there won't be a unicodePwd attribute so the more common userPassword attribute will be set instead.

The default is MF, unless the password verification mode is set to bind, in which case the default is compatible. Note that the MLDAP ESM Module does not currently support the LDAP Modify Password Extended Operation (RFC 3062). Also note that Active Directory, and possibly other servers, only allow password changes over a secure LDAP connection (SSL/TLS or otherwise encrypted) by default; see your LDAP server documentation for more information.

password attribute=name
Overrides the name of the attribute of the user class that contains password data, for setting passwords. See the descriptions of the password types above for the defaults.

[Trace] section

Rule=setting
Enable the logging of the "effective rule" for resource-access decisions. If this is set to a string beginning with "y" or to "1", the ESM Module will make a log entry for every authorization decision noting which rule was used to make the decision.
Groups=setting
Log various messages regarding the processing of user groups. If this is set to a string beginning with "y" or to "1", the ESM Module will make a log entry when it determines that a user belongs to a group during Verify, or when it finds a group ACE that applies to a request during Auth. This is particularly useful when debugging problems with All-Groups mode.
Search=setting
Enable the logging of some LDAP search operations. (Not all searches are currently logged.) If this is set to "fail", the ESM Module will make a log entry for every search that returns an error other than "not found". (During Auth requests, there will typically be many searches that return "not found"; the "fail" setting avoids logging these normal unsuccessful searches.) If it is set to "found", the module will log all searches that succeed or return an error other than "not found". If it is set to "all", "y", or "yes", it will log all search operations, including ones that return "not found".
Modify=setting
Enable the logging of some LDAP modify operations which are normally not logged. If this is set to "fail", the ESM Module will make a log entry if one of these "silent modify" operations fails. If it is set to "all", "y", or "yes", it will log all of these modify operations, including ones that succeed. Currently affected operations include setting the last-login-time user attribute, and possibly others.
Bind=setting
Enable the logging of LDAP bind operations. If this is set to a string beginning with "y" or to "1", the ESM Module will make a log entry when it binds to the LDAP server. This may be useful if you are investigating an issue with network traffic to the LDAP server.
Locks=setting
Enable the logging of intra-process and inter-process locking. If this is set to a string beginning with "y" or to "1", the ESM Module will make a log entry when it tries to acquire, acquires, or releases a lock. Micro Focus SupportLine may ask you to enable this tracing mode to diagnose certain unlikely problems.
Update=setting
Enable the logging of update requests, which are ESF control requests (made using MFDS or the esfupdate command-line utility) that notify ESF and the ESM Modules of changes to security configuration or data. If this is set to "y" or "yes", update requests will be logged. If it is set to "changes", additional messages will be logged when an update request causes the module to change internal state, such as the MSS attributes (operator class, etc) of a user or a user's group membership. If it is set to "all", additional messages are logged when an update request does not cause changes.
TraceN=rule
Define a rule for filtered tracing. Filtered tracing lets you trace only requests that meet a set of conditions, defined by the tracing rule. N in the name is a number from 1 to 8 (the maximum number of filtered-tracing rules): Trace1, Trace2, and so on. (You can define rules out of order and skip numbers - they only need to be unique and between 1 and 8.)

A tracing rule has the format:

function:actor[:parameters]:result

where:

  • function is verify or auth
  • actor is a username; for auth rules, it can also be a group name followed by the word group. Wildcards are allowed.
  • parameters specific to the function:
    • For verify, there are no parameters
    • For auth, this must be class:entity, where:
      • class is a resource class name (eg "TCICSTRN"); wildcards are allowed
      • entity is a resource entity name (eg "CINQ"); wildcards are allowed
  • result is allow, deny, unknown, fail, any, or debug

The request will be traced if all of the conditions of the rule are met. Tracing means one or more informational messages about the request will be written to the log. A result setting of debug will log based on any result (like any), but will also log additional information during processing a request that matches the function, actor, and parameters.

Examples:

  • verify:SYSAD:deny will trace Verify (signon) requests where the SYSAD user is denied
  • auth:SYSADM group:TCICSTRN:C*:allow will trace Auth (authorization) requests where a member of the SYSADM group requests access to any resource in the TCICSTRN class with a name beginning with C, and the request is allowed

Filtered tracing is useful in isolating issues on busy systems, where normal tracing would produce excessive output. It does affect performance somewhat, since each request must be examined to see if it matches a trace rule.

Be sure to use a double asterisk (**) in wildcard specifications for dataset names, if you want them to match qualifiers. For example, use auth:SYSAD:DATASET:**:deny to see all cases where SYSAD is denied access to a dataset.

Parent topic: MLDAP ESM Module Configuration Fields
Related concepts
Federation in the MLDAP ESM Module
"Use all groups" Mode
Configuring the ESF LDAP Security Administration Web Interface


Using All Groups to Which a User Belongs

Each user can belong to one or more user groups, and resource permissions can be assigned to groups as well as to individual users. Like some mainframe security managers, ES MSS has the concept of a "sign-on group": during sign-on, users can also specify which group they're signing on with. (If the user isn't in the specified group, the sign-on is denied.) Users who don't specify a group sign on under their "default group", as determined by the ESM.

By default, when a user requests access to some resource, some ESMs will only apply rules that refer to that user and the user's current sign-on group. (Other ESMs may ignore the concept of sign-on group entirely, and always apply rules that refer to any group the user belongs to.) Rules for other groups will be ignored, whether the user belongs to them or not.

You can set the Use all Groups option in an enterprise server's security configuration to change this behavior. If Use all Groups is set, it doesn't matter what a user's sign-on group is; the user will always have all the permissions that apply to any group that user belongs to.

Parent topic: MLDAP ESM Module


Federation in the MLDAP ESM Module

The ESF Federation setting affects how instances of the MLDAP ESM Module work together, when multiple ESMs using the MLDAP ESM Module are stacked in the security configuration. Federation is not a concern if there is only one MLDAP ESM Module in the stack.

If federation is disabled, the MLDAP ESM Module will ignore any Auth and XAuth operations that refer to users which are not known to that module. For example, suppose you have two LDAP repositories, with some of your users defined in the first repository and the other users defined in the second. To accommodate this configuration you have created a security configuration with two MLDAP ESM Modules on the stack, one pointing to the first LDAP repository and the other to the second. Assume the user Alice is defined in the second repository and that federation is disabled. When Alice tries to access a resource, ESF will make an Auth request to each ESM in turn. The first ESM does not have information about Alice, as she's defined in the second ESM, so it will return "unknown" for the Auth request. The second ESM will then process the request normally. That means resource ACLs defined in the first ESM will not be consulted when determining Alice's access.

If federation is enabled, or is set to compatibility mode (currently the default), then the first ESM will look for resource ACLs that apply to the Auth request, even though it was not the ESM that verified the user Alice.

Federation also affects use-all-groups mode. If federation is enabled, all MLDAP ESM Modules in the process will share a single set of group names and group membership information. If federation is disabled, each MLDAP ESM Module will have its own set of group names and group membership information. In federation compatibility mode, there is only one set of group names shared by all modules, but each module has its own information about what users belong to each group.

The compatibility federation setting can lead to unexpected results, since an ESM may not have group information for a user and so may not apply group-based ACLs as you expect. When using multiple MLDAP ESM Modules, it's usually best to explicitly enable or disable federation, especially if use-all-groups mode is enabled.

In general, you should enable federation if you want your LDAP security information combined, as if it all came from a single LDAP repository. You should disable federation if your LDAP repositories are designed to be independent (so, for example, resource access rules from one LDAP repository should not be applied to users from the other repository).

If redundant (also known as high-availability) mode is enabled for ESF itself, federation is automatically enabled.

Parent topic: MLDAP ESM Module
Related concepts
Access Levels and Permissions
"Use all groups" Mode


Configuring Operating System Security: osesm

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
Parent topic: Active Directory


How osesm Works

With the osesm security manager, users sign on to MFDS, Enterprise Server Administration, and/or MSS 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

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 Active Directory

This section describe the methods available for configuring Microsoft Active Directory (AD) to provide Enterprise Server security.

The topics in this section illustrate the process by describing how you perform it using Microsoft's Active Directory Lightweight Directory Service (AD LDS) software.

UNIX appears in bold at the start of a paragraph that applies to performing the procedure using Enterprise Server for UNIX rather than Enterprise Developer for Windows.

  • Setting Up Security with AD LDS
    AD LDS is a lightweight stand-alone LDAP server that is similar in functionality to Active Directory. You can use the procedures in this section to become familiar with LDAP security.
  • Preparing Active Directory for Enterprise Server Security
    This section describe the procedures you need to perform for both of the following sections: using the MLDAP and the OSESM security managers in conjunction, and using the MLDAP security manager only.
  • Configuring Windows Users as Enterprise Server Administrators
    This section describes the procedures for verifying Enterprise Server administration using Windows authentication for user accounts stored in Active Directory.
  • Configuring Active Directory Users as Enterprise Server Administrators
    This section describes the procedures for configuring users defined in Microsoft Active Directory (AD) as Enterprise Server administrators. It describes how to grant the necessary permissions to the Windows users defined in AD, and how to configure Enterprise Server to use AD as its security manager.
Parent topic: Securing an Enterprise Server Installation


Setting Up Security with AD LDS

The topics in this section describe how to install and configure AD LDS for use with Enterprise Server's MLDAP_ESM security manager.

AD LDS is a stand-alone LDAP server that is very similar to Active Directory. The key difference is that, unlike Active Directory, AD LDS can be deployed on a server that is not a domain controller. (AD LDS was known as ADAM (Active Directory Application Mode) in previous releases.)

Even if you do not intend to use AD LDS as your LDAP, it is useful to follow the procedures in this section to familiarise yourself with what is involved. This will be a useful exercise if you want to use a more fully-featured LDAP such as Active Directory, or OpenLDAP.

  • ldifde Notes
  • Installing Active Directory Lightweight Directory Service (AD LDS)
  • Creating the AD LDS Server Instance
  • Running the Setup Script
  • Configuring Microsoft Users
  • Configuring Enterprise Server to use the MLDAP ESM
  • Configuring the AD LDS Repository
Parent topic: Configuring Security using Active Directory


ldifde Notes

Several of the steps in this process use the Microsoft ldifde utility, a relatively complex command-line utility with many options. You may want to read the documentation for ldifde that comes with AD LDS.

Here are some tips for using ldifde:

  • We use ldifde to read an LDIF file (with an .ldf extension) and update AD with the objects listed in the file. LDIF files are text files and can be edited in Notepad.
  • Many of the ldifde command lines shown below use the "-c" option, which takes two strings as parameters, and changes the first string to the second wherever it appears in the input. So "-c DC=X DC=mydom,DC=com" will change "DC=X" in the .ldf file to "DC=mydom,DC=com". That lets you customize the information in the .ldf file for your installation.
  • You can copy the .ldf files to your AD server and run ldifde there, or you can run it on a system with Enterprise Developer installed and update AD remotely.
  • ldifde has to bind (log on to) AD in order to make changes to the directory. If you are not logged on as an authorized AD user, you can add "-b username domain password" to the ldifde command line.
  • When we show ldifde command lines below, we use the "-s servername" option to tell ldifde the hostname of the AD server. If you're running on the AD server, or if your AD server is the domain controller for the domain that you are running in, you can leave off the "-s servername" option.
  • Each time you run ldifde (with the "-j ." option), it will create an ldif.log file in the current directory. If there are errors or warnings, it will create an ldif.err file as well. If the files already exist, they will be overwritten. We recommend you rename the log file after each ldifde run (for example eg to ldif-1.log, ldif-2.log, etc) so you can send them to Micro Focus Support if you have problems. If an ldifde command fails, you can check the log and error files for more information.

A typical ldifde command will have these parts:

Ldifde | Command name
-i | Command type: import data into AD
-f filename.ldf | Specify LDIF file to import from
-s servername | Hostname of AD server
-k | Keep going even if some entries can't be processed
-j | Create log files in current directory
-c from-string to-string | Change from-string in data to to-string. This lets you customize a generic LDIF file for your installation. For example, from-string might be the placeholder DC=X, and to-string might be your domain DN.
Parent topic: Setting Up Security with AD LDS


Installing Active Directory Lightweight Directory Service (AD LDS)

You can download a copy of Active Directory Lightweight Directory Service (AD LDS) from the Microsoft website. Run the downloaded software and follow the prompts to install it.

Parent topic: Setting Up Security with AD LDS


Creating the AD LDS Server Instance

An AD LDS instance acts an LDAP server. This process describes how to create a server instance specifically for Enterprise Server use.

  1. Click Start > Administrative Tools > Active Directory Lightweight Directory Services Setup Wizard
  2. In the wizard screens select the following options and use the following values:
    Setup Options page
    Select the option A unique instance.
    Instance Name page
    In the Instance name field, enter: MFES.
    Ports page
    Accept the default LDAP and SSL ports: 389 and 636.
    Application Directory Partition page
    Select the option Yes, create an application directory partition and enter the name CN=Micro Focus,CN=Program Data,DC=local.
    File Locations page
    Accept the default file store location (or specify a custom one - this should make no difference).
    Service Account Selection page
    Select to run the service using the Default network service account and override any warning messages that appear.
    AD LDS Administrators page
    Use your current logged-on account (note that you can create an additional AD LDS administrative account in a later step, in case you do not normally use an Administrative account)
    Importing LDIF Files page
    Select the option Import the selected LDIF files, and from the list, select MS-User.LDF to be imported.
  3. On the final wizard screen, click Next to create the instance with your configurations.

As the instance is created, messages appear to show the progress. You may be prompted by your firewall. If so, configure it appropriately to allow your AD LDS instance to accept connections at least from localhost on port 389.

Parent topic: Setting Up Security with AD LDS


Running the Setup Script

The es-ldap-setup script defines the LDAP object classes and containers (the schema) that will hold ES data. That is, it configures AD LDS or AD so that you can use it with Enterprise Server.

By default, the script is installed by default into the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory.

You can run es-ldap-setup with no parameters to configure the default settings. When you run the script, check that it generates no errors.

Without parameters, the script displays the default it will set, and prompts you for information if you do not want to accept the default. Press Enter to accept the default values unless you need to specify something else.

These are the actions es-ldap-setup performs:

  1. Prompts for values such as username if they are not specified on the command line. Press Enter to accept the default, or supply a different value.
  2. If AD LDS or AD is not configured to allow password operations over unsecured connections, the script will configure it to allow them. This is required by some of the following actions. If the script changes this option on the server, it will reset it to its old value before exiting.
  3. Adds the ES user, group, and resource LDAP class definitions to the schema. These specify what attributes each of these types of object has.
  4. Adds the container objects for ES to the repository.
  5. Creates MFReader, the default LDAP user account for ES.
  6. Creates the administrative LDAP user for adding MSS users. (This step is skipped if the /AD option is specified.)
  7. Imports MSS users that are defined in the default MSS resource definition file into the LDAP repository.
  8. Imports MFDS users and groups into the LDAP repository.
  9. Imports the default MSS resource access control definitions into the LDAP repository.
  • The es-ldap-setup AD Setup Script
Parent topic: Setting Up Security with AD LDS


The es-ldap-setup AD Setup Script

The es-ldap-setup script defines the LDAP object classes and containers (the schema) that will hold ES data. That is, it configures AD LDS or AD so that you can use it with Enterprise Server.

By default, the script is installed by default into the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory.

The full syntax for es-ldap-setup is:

es-ldap-setup [/?] [/AD] username password partition server
  • The /? option will display a syntax message and information about what actions the script will perform.
  • The /AD option tells the script that you are using AD rather than AD LDS, so it will not try to create an LDAP administrative user account.
  • The username should be the name of an existing or new administrative user for the LDAP server. (For AD, this user must already exist and have suitable permissions.) It defaults to the current user's name.
  • Password is the LDAP administrator's initial password; it defaults to "password". You can change this password (or even disable or remove the administrative user account created by the script) after the script runs.
  • The partition parameter specifies the LDAP distinguished name (DN) of the application partition where the ES LDAP objects should be created. The default is "CN=Micro Focus,CN=Program Data,DC=local", which is generally suitable for use with AD LDS, but AD users will probably need to specify the DN of a container within their corporate LDAP hierarchy. See your LDAP administrator for more information.
  • The server parameter is the hostname and port of the LDAP server. It defaults to "localhost:389", which is the standard address for an LDAP server running on the local machine.

Most users will run es-ldap-setup with no parameters, but in some cases you may want to specify a username and password:

  • If you're running es-ldap-setup under your normal login ID, and using your local AD LDS installation as your LDAP server, just run it with no parameters.
  • If you're using ES with AD, specify the /AD option and all four parameters. Provide the username of a user with administrative access to AD, and that user's password; the DN of the part of the LDAP repository that will hold ES data; and the hostname and port of the AD server.
  • If you're running es-ldap-setup under an administrative account that isn't your normal login ID, it's usually best to specify your normal login ID as the username. That way, if you want to run the cas-to-ad utility in the future, you can run it under your normal login ID rather than having to specify a different user.
  • If you want a password other than the default "password", specify both the username and password parameters.
  • If you need to specify one parameter, you also have to provide values for the parameters before it. For example; if you need to specify a different LDAP server, you'll have to provide username, password, and partition as well.

These are the actions es-ldap-setup performs:

  1. Prompts for values for username, etc, if they are not specified on the command line. Press Enter to accept the default, or supply a different value.
  2. If AD LDS (or AD) is not configured to allow password operations over unsecured connections, the script will configure it to allow them. This is required by some of the following actions. If the script changes this option on the server, it will reset it to its old value before exiting.
  3. Adds the ES user, group, and resource LDAP class definitions to the schema. These specify what attributes each of these types of object has.
  4. Adds the container objects for ES to the repository.
  5. Creates MFReader, the default LDAP user account for ES.
  6. Creates the administrative LDAP user for adding MSS users. (This step is skipped if the /AD option is specified.)
  7. Imports MSS users that are defined in the default MSS resource definition file into the LDAP repository. See Adding MSS Users to the LDAP Repository for more information.
  8. Imports MFDS users and groups into the LDAP repository.
  9. Imports the default MSS resource access control definitions into the LDAP repository.

Before each action, es-ldap-setup will pause and tell you what it's about to do. When it finishes, it will report how many actions succeeded and how many failed, and give a list of the failing actions, which you can provide to Micro Focus Support if you have questions.

Note: Some users may encounter a known issue with the AD LDS dsmgmt utility when running the script. If you get an error message similar to the following:
DsBindWithSpnExW error 0x6ba (The RPC server is unavailable.)

then there is an issue with your network configuration which is preventing the utility from connecting to your AD LDS server. This is a Windows issue, not a Micro Focus one. Possible fixes include:

  • Remove IPv6 support from your network configuration.
  • Specify the LDAP server address for the script using your local hostname rather than localhost. (Remember to include the port number, as in myhost:389.)
  • Disable your local system's firewall while running the script. With some application firewalls, such as Symantec Client Security, disabling the firewall may not be sufficient, and you may have to manually disable or delete rules that affect the ICMP protocol.
  • Check that your hosts file (%systemroot%\system32\drivers\etc\hosts) does not contain any invalid entries for localhost or your local hostname.
Parent topic: Running the Setup Script


Configuring Microsoft Users

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.

  • To Configure a Security Manager's Environment
Parent topic: Setting Up Security with AD LDS
Related tasks
To Configure a Security Manager's Environment
Related information
To configure the security facility to use the MLDAP ESM


To Configure a Security Manager's Environment

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"
Parent topic: Configuring Microsoft Users
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


Configuring Enterprise Server to use the MLDAP ESM

After you have successfully configured your LDAP server, you can configure Enterprise Server to use LDAP for security.

  1. Create a Security Manager object in MFDS. The security manager that you create must use the following options:
    • Module: mldap_esm.
    • Connection Path: the hostname and port of your LDAP server, just as you supplied it on the es-ldap-setup command line. You can leave it blank if you're using a local AD LDS (or AD) server.
  2. Once the security manager has been created, enable it for a specific ES server, for example ESDEMO.
    CAUTION:
    Do not configure this ESM for MFDS until you have tested it with an ES server.
  3. Start the Enterprise Server, using the SYSAD user ID (password SYSAD). This ID is created in the AD LDS LDAP by the setup script.

    The enterprise server starts, using the AD LDS LDAP to authenticate the SYSAD user.

Parent topic: Setting Up Security with AD LDS


Configuring the AD LDS Repository

This section describes the tasks you can use to create, view, and edit your ES LDAP security configuration.

  • Browsing the AD LDS Repository
  • Adding Repository Objects using ADSIEdit
  • Adding MSS Users to the LDAP Repository
  • Enabling MFDS Administration for LDAP and User Password Changes
Parent topic: Setting Up Security with AD LDS


Browsing the AD LDS Repository

You can use the Microsoft ADSIEdit utility to view the ES areas of your LDAP repository. This tool is included with AD LDS. You can run it from the Start Menu.

  1. Click menu, select Start > Administrative Tools > ADSI Edit to open the editor.
  2. In the editor's menu, select Action > Connect to... to open the Connection Settings dialog box.
  3. In the the Connection Settings dialog box, enter the following details to create a connection to the ES application partition:
    • Connection name: MF or a name of your choosing.
    • Server name: localhost
    • Port: 389
    • Connect to the following node: select the Distinguished name (DN) or naming context radio button.
    • DN value to enter: CN=Micro Focus,CN=Program Data,DC=local
    • Connect using these credentials: select the The account of the currently logged-on user radio button.
  4. Click OK.

The left pane displays a tree view item with the name that you configured as the connection name. When you expand this item, and then the container within it, the ES containers are displayed, for example
        CN=Enterprise Server Users,
        CN=ADAM Users, and automatically-generated containers such as
        CN=Roles.

You can open these containers and double-click on the objects within them to view (or edit) their attributes.

Parent topic: Configuring the AD LDS Repository


Adding Repository Objects using ADSIEdit

You can also use ADSIEdit to create new objects in the repository, such as new MSS users, using Action > New. Select the appropriate object type, then complete the wizard, which will prompt for required values and give you an opportunity to enter optional ones. (You can change any of these later by editing the object.)

Creating an MSS user

  • To create an MSS user, select the CN=Enterprise Server Users container, right-click and select to create a new microfocus-MFDS-User object:
    • Set the cn attribute to the username
    • The dialog will prompt for some mandatory MSS attributes such as microfocus-MFDS-User-MTO-Timeout. You can set the Timeout, Priority, and OperatorClass attributes to 0 (or any other value which is valid under MSS).
    • Set the microfocus-MFDS-User-AllowLogon attibute to TRUE.
    • The microfocus-MFDS-UID attribute must be set, but currently the format of this value does not matter. You can set it to the username, for example.
    • If you want to set an initial password, when you reach the final page of the dialog (with the "Finish" button), click More Attributes, find the microfocus-MFDS-User-Pwd attribute, and double-click it. Set its value to "literal:password". Note that this password will be stored in plaintext (and so will be visible by anyone who has read access to the repository) until you change it.
    • Other optional attributes you may want to set:
      • displayName to the user's "display" name (often a person's legal name, etc)
      • description to any descriptive text you want to associate with the user
      • microfocus-MFDS-User-DefaultGroup to the user's default MSS group (eg ALLUSR)
      • microfocus-MFDS-User-MTO-GroupPrefix and microfocus-MFDS-User-MTO-OperatorID if you use MSS group prefixes and/or operator IDs with your normal MSS user definitions
      • microfocus-MFDS-User-CreateToken and microfocus-MFDS-User-UseToken if you use passtokens (typically, set both of these to self for users who will be using MFDS and ESMAC)

Creating an MSS user group

  • To create an MSS user group, right-click the CN=Enterprise Server User Groups" container and select to create a new microfocus-MFDS-Group object:
    • Set the cn attribute to the group name. Note that this name must be no longer than 8 characters.
    • The microfocus-MFDS-UID attribute must be set, but currently the format of this value does not matter. You can set it to the group name, for example.
    • To set the members of the group (you can change this later by editing the group object), click More Attributes on the final page of the dialog. Double-click the microfocus-MFDS-Group-Member attribute to get a dialog that lets you add or remove members.
    • Each group member can be either the name of a user (the cn of a microfocus-MFDS-User object), or the name of another group preceded by the keyword group. For example, adding "group DEV" as a member to the ALLUSERS group makes all members of DEV members of ALLUSERS as well. You can use this to organize groups into hierarchies or create very large user groups.

Creating a resource class and resource access control object

  • To create an MSS resource class, right-click the CN=Enterprise Server Resources container and create a new container object. Set its cn attribute to the name of the resource class.
  • To create an MSS resource access control object, expand the CN=Enterprise Server Resources container in the tree view, then right -click the container for the class of the resource you want to create. Create a new microfocus-MFDS-Resource object:
    • Set the cn attribute to the resource name, or to a string that contains wildcards to create a generic rule. Wildcards are explained in the documentation for the MLDAP ESM Module in your product documentation.
    • The microfocus-MFDS-UID attribute must be set, but currently the format of this value does not matter. Since resource names can be long, it may be easiest just to put a dummy value here, such as 1.
    • You must set the microfocus-MFDS-Resource-Class attribute, but this attribute is no longer used and is only in the schema for compatibility with pre-release versions. You can set this to the resource's class name or to any other value.
    • If you want to set an initial ACL, click More Attributes on the final page of the dialog. Double-click the microfocus-MFDS-Resource-ACE attribute to get a dialog that lets you add or remove access-control entries. See MLDAP ESM Module for more information.

You may want to create a new AD LDS user for ES to use. If you want to give ES permission to change objects in the repository -to let users change their passwords when they sign on, or to enable LDAP administration through MFDS - then you will want to configure the MLDAP Security Manager in MFDS with a different Authorized ID and Password. (It's not safe to give the default MFReader account write permission to the repository, because that username and its password are available to anyone who reads the ES LDAP setup materials.)

Creating an AD LDS user

  • To create an AD LDS user, expand the CN=AD LDS container, then create a new user object:
    • The cn is the only required attribute.
    • After creating the user, you can give it the appropriate permissions by editing the appropriate object in the CN=Roles container and double-clicking on the member attribute, which will give you a dialog box where you can add users to that role. Adding your new user to the Administrators role will give it administrative access to the repository, for example.
    • You can also give your new user more specific permissions by editing the ACLs for specific parts of the repository. See the AD LDS documentation for more information.
Parent topic: Configuring the AD LDS Repository
Related concepts
MLDAP ESM Module


Adding MSS Users to the LDAP Repository

Many existing ES/MSS customers have created multiple MSS resource definition (RDO) files, to configure various ES servers (or "regions"). These RDO files may contain users defined for MSS. The es-ldap-setup script reads the default RDO file (located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\cas\dfhdrdat directory) and adds any user definitions in it to the LDAP repository. If you have other RDO files, though, you may want to extract user definitions from them and import them into LDAP for use with ES external security.

You can use the cas-to-ad.exe utility to migrate MSS user definitions into LDAP. Run "cas-to-ad -h" to get a syntax message. Current options are:

Option | use To | Default
-u user | Set username for AD connection (name or DN) | Current logon name
-p password | Set password for AD connection | None; if not set, you will be prompted
-d DN | DN for AD application partition | CN=Micro Focus,CN=Program Data,DC=local
-c container | container for added ES users | CN=Enterprise Server Users
-l host:port | Location of the AD server | localhost:389
-r path | Path to CAS RDO file | See below
-e encoding | Password encoding | md5 (the other option is "literal")
-v | Show version and exit | N/A
-h | Show syntax help and exit | N/A

Option values can be appended to the option character or specified as the next argument on the command line.

The CAS RDO file (always named dfhdrdat) that cas-to-ad will process is located as follows:

  1. If the -r option is used, cas-to-ad uses the specified path
  2. If not, cas-to-ad looks to see if the environment variable TXRDTP is defined, and if so uses that path
  3. If not, it looks for a dfhdrdat file in the current directory, and if one is present uses it
  4. If not, it looks for the Enterprise Developer or Enterprise Server base directory Registry key, and uses the \etc\cas\dfhdrdat under that directory.

The -e option controls how user passwords are stored in LDAP. The default is -e md5, which stores a salted MD5 hash of the password. The value of the microfocus-MFDS-User-Pwd attribute will have the form "MF-MD5:base64-salt:base64-hash", where base64-salt and base64-hash are character strings that contain base64-encoded data. This is an irreversible transformation (the hash can be used to verify the password but not to reconstruct it). The other encoding currently supported is -e literal, which stores the password in plain text, in the form "literal:password". This form is useful for debugging and when creating ES users using ADSIEdit.

Parent topic: Configuring the AD LDS Repository


Enabling MFDS Administration for LDAP and User Password Changes

By default, ES uses the MFReader account to connect to the LDAP server. As its name suggests, MFReader does not have authority to make changes to the repository, only to read from it.

You may want to configure your MLDAP Security Manager in MFDS with different LDAP user credentials (Authorized ID and Password), to give it update access to part or all of the repository. You can configure it with credentials for an administrative user, or create a new LDAP user (see Adding Repository Objects using ADSIEdit) and then set ACLs in the LDAP repository (using ADSIEdit or other Microsoft tools) to give that user write access to specific parts of the repository.

For example, if you have created an AD LDS user named "MFUpdate", you could give it write access to user objects by setting an ACL with the dsacls.exe AD LDS utility:

dsacls "\\localhost\CN=Enterprise Server Users,CN=Micro Focus,CN=Program Data,DC=local" /I:S   /G "CN=MFUpdate,CN=ADAM Users,CN=Micro Focus,CN=Program Data,DC=local":WP

(Enter this command all on one line.)

You should not give the MFReader LDAP user write access to the repository, because its name and password are well-known. Configure your security manager to use a different account instead, and be careful to keep that account's password a secret. (If non-privileged users have access to the system where MFDS is running, it's a good idea to set ACLs on the MFDS configuration files so that they can only be read by the account MFDS runs under, which is usually SERVICE.)

If an ES/MSS region is configured to use a MLDAP Security Manager that has update access to user objects, then interactive MSS users will be able to set their passwords when they sign on to the system (using the CESN transaction, or another program that calls the EXEC CICS SIGNON interface). This is particularly useful if you make use of the password expiration date attribute (microfocus-MFDS-User-Pwd-ExpirationDate) to force users to change passwords periodically, since it gives them a way to do so. (Note that the MLDAP ESM Module does not currently provide any way to automatically set the expiration date; that has to be done using some other tool.)

If MFDS is configured to use an MLDAP Security Manager that has update access to the various ES objects in the LDAP repository, then you can use MFDS to administer those objects. From the Security page of the MFDS administration GUI, go to the Security Managers tab, edit the Security Manager you have defined for LDAP, and click its Properties button. From there, you can view and edit users, groups, and resource access controls.

Parent topic: Configuring the AD LDS Repository


Preparing Active Directory for Enterprise Server Security

  • Prerequisites
  • Command Window and PATH
  • Establishing a Work Directory and Copying Files
  • Extend the AD Schema
  • Create LDAP Objects
  • Final User Tasks
  • Configure ES Security
Parent topic: Configuring Security using Active Directory


Prerequisites

Software

To perform the procedures in this section, you will need the following software:

  • ldifde.exe, the Microsoft LDAP utility that is shipped with AD LDS.
  • Enterprise Server MFDS and the cas-to-ad utility, which are supplied with the product install.

    UNIX: The cas-to-ad step is optional; if you don't need to import existing MSS users, you can use a UNIX SX5.0 WS03 or greater environment instead, and run the ldifde commands on the domain controller.

  • The following LDIF (LDAP data) files are in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory.
    • mf-partition.ldf
    • mf-ad-containers.ldf
    • ms-user-plus-mto.ldf
    • es_default_ldap.ldf or es_default_ldap_msuser.ldf (only one of these is used)

Information

You will need the following:

  • A user account authorized to make AD schema changes (shown as username and password below).
  • The location of the AD server (shown as servername below).
  • The user class you will use.

    This can either be microfocus-MFDS-User (supplied by Micro Focus), if ES users will be separate from Windows users, or user (supplied by Microsoft and modified by Micro Focus) to use your Windows user accounts for ES. (Shown as userclass below.)

  • The DN of the AD domain (shown as domain-DN below).

    Normally, this will be the fully-qualified domain name of the AD host, minus the hostname, with each segment of the name listed as a separate DC element, so for example server.dept.mydom.com would use DC=dept,DC=mydom,DC=com. If you are using AD LDS, you may want to use the default domain DN for ES LDAP data, which is "CN=Micro Focus,CN=Program Data,DC=local".

  • The DNs of the containers for users, ES user groups, and ES resources, if you are going to use something other than the default values.

    ES groups and resources are used only by ES, so we recommend you use the defaults (located in CN=Micro Focus,CN=Program Data) for their containers.

    If you are using the Micro Focus user class (microfocus-MFDS-User), you can use the default ES user container (CN=Enterprise Server Users,CN=Micro Focus,CN=Program Data, below the domain-DN) as well.

    On the other hand, if you want to let existing Windows users sign on to ES without creating separate ES user accounts for them, you will need to configure ES to use your existing user container in AD (usually CN=Users). Use that for your user container (shown as user-container below) in the following commands as well.

Backups

Before you make any AD modifications we recommend you back up your AD schema and Directory Information Tree (DIT). You may already have standard procedures for this. If not, you should make a backup of the contents of the %WINDIR%\ntds directory to another location. This way you can drop the server (assuming Server 2003) into "Directory Server Recovery" mode and restore your previous AD data if you ever have to.

Note that the contents of that directory are in use when the server is running, so ordinary copy commands generally will not work. Some ways you can back up your AD information:

  • Make the backup in Directory Server Recovery Mode (press F8 while booting the AD host to enter Recovery Mode)
  • Use a backup utility such as the Backup applet that comes with Windows, or the ntbackup command-line equivalent (this does not require a reboot)
  • Use a utility to schedule a copy when the system is rebooted, such as SysInternals movefile (and then reboot to effect the copy)

Consult your Windows documentation for more information.

You may also want to export your current LDAP hierarchy to an LDIF file for later reference, using a command such as:

ldifde -f export-file -s servername -r "(objectclass=*)" -d "CN=Schema,CN=Configuration,domain-DN"
Parent topic: Preparing Active Directory for Enterprise Server Security


Command Window and PATH

Some of the commands described in the procedures in this section require the correct environment. To achieve this, use an Enterprise Developer command prompt. This is available from Start > All Programs > Micro Focus Enterprise Developer > Tools > Enterprise Developer Command Prompt.

After opening the command prompt, use the following command to add the AD LDS installation directory to your path:

path %windir%\ad lds;%path%

The mfds and cas-to-ad commands need to be run from a system with Enterprise Developer installed. The ldifde command can be run on the domain controller instead, if you find that more convenient.

UNIX: On UNIX, you will need a terminal session with the appropriate environment settings to run the binaries. The cas-to-ad command is not currently supported; if you have CICS SNT users you wish to import into Active Directory, contact Micro Focus Support for more information.

Parent topic: Preparing Active Directory for Enterprise Server Security


Establishing a Work Directory and Copying Files

We recommend creating and using a new work directory for this procedure, as that makes it easier to keep track of the files you use and create:

mkdir mf-ad-setup
cd mf-ad-setup

After creating your work directory, you will need to copy the LDIF files into it. These files are in the Base\Bin directory of your product installation.

If these files are not included with the product, contact Micro Focus Support.

Parent topic: Preparing Active Directory for Enterprise Server Security


Extend the AD Schema

Create the Micro Focus AD format schema extension LDIF file (enter this and all other commands on a single line):

mfds -L "CN=Schema,CN=Configuration,domain-DN" 1 mfds-schema.ldf

This will create the file mfds-schema.ldf. Use the latest WS03 build MFDS (1.06.11 or later) for this operation to ensure you have the latest schema definitions.

Import MF schema extensions into AD:

ldifde -i -f mfds-schema.ldf -s servername -k -j .

If you are updating a remote AD server, this command may take a minute or two. When it's done, remember to rename the log files, as described above.

Note: If you want to use the Microsoft user object class for your ES users, you must extend it with additional Micro Focus attributes:
ldifde -i -f ms-user-plus-mto.ldf -s servername -k -j . -c "DC=X" "CN=Schema,CN=Configuration,domain-DN"
Parent topic: Preparing Active Directory for Enterprise Server Security


Create LDAP Objects

  • Containers
  • ES/MSS Objects
Parent topic: Preparing Active Directory for Enterprise Server Security


Containers

Create the Micro Focus partition. You will need to edit the mf-partition.ldf file first if you do not want to use CN=Micro Focus,CN=Program Data as the container for the ES definitions.

ldifde -i -f mf-partition.ldf -s servername -k -j . -c "DC=X" "CN=Program Data,domain-DN"

You can copy the .ldf files to your AD server and run the command there, or run it from a system with Enterprise Developer.

Next create the standard MF containers. If you want to use a different container for users, user groups, or resources, you may need to edit the mf-ad-containers.ldf file first. You may also have to edit some of the other .ldf files or make changes to some of the commands that follow.

We recommend using the standard containers, with one exception: if you are using Windows users for ES users, you will want to use the existing AD user container. You don't need to do anything different in this step for that.

The command to create the standard MF containers is:

ldifde -i -f mf-ad-containers.ldf -s servername -k -j . -c "DC=X" "CN=Micro Focus,CN=Program Data,domain-DN"
Parent topic: Create LDAP Objects


ES/MSS Objects

Import the predefined ES/MSS users, user groups, and resource access control definitions from the default LDAP configuration into your AD repository. The LDIF file you use depends on the user class you have chosen.

Run only one of the following two commands.

  • If you are using the default, ES-only microfocus-MFDS-User class:
    ldifde -i -f es_default_ldap.ldf -s servername -k -j . -c "DC=X" "domain-DN"

    es_default_ldap.ldf uses the default Micro Focus containers for ES users, groups, and resources.

  • If you are using the Microsoft user class, so that Windows users can also be ES users:
    ldifde -i -f es_default_ldap_msuser.ldf -s servername -k -j . -c "DC=X" "domain-DN"

    es_default_ldap_msuser.ldf uses the default Micro Focus containers for ES groups and resources, and the default AD user container (CN=Users) for users.

When you run this command, you will probably get warnings about objects that do not exist. You can ignore these warnings. They are generated because these .ldf files try to delete any existing instances of the objects they create.

Parent topic: Create LDAP Objects


Final User Tasks

Some user attributes may need to be set manually (using AD administration tools or hand-written LDIF files) after importing the ES definitions.

  • Set MSS Attributes for Windows Users
  • Enabling ES Predefined Users
  • Disable Password Expiration for ES Users
  • Remove Predefined Users
  • Configuring the Default ESMAC User
Parent topic: Preparing Active Directory for Enterprise Server Security


Set MSS Attributes for Windows Users

If you are using your existing Windows users as ES users, you will probably want to set some of the new MSS-specific user attributes for at least some of them. For example, the microfocus-MFDS-User-MTO-Timeout attribute sets the MSS timeout for that user. See the ES/MSS documentation for more information.

You will also probably want to add existing users to MFDS and MSS user groups to reflect their roles (developers, administrators, etc). Note these are ES user groups, not Windows user groups, so you change them by modifying your AD repository with an LDIF file or a tool such as ADSIEdit. The ES/MSS documentation includes information on ES user groups. For example, you can add Windows users to the #DSAdmin group in Enterprise Server User Groups to make them MFDS administrators; to give a user permission to start and stop ES regions, set their default group attribute microfocus-MFDS-User-DefaultGroup to SYSADM.

You can make these changes manually using a tool for administering AD data, such as ADSIEdit. For bulk changes, though, you will probably want to create LDIF files to update multiple users, groups, or resources at once.

Parent topic: Final User Tasks


Enabling ES Predefined Users

If you use the Microsoft user object class, AD will probably disable the new predefined ES users. If you want to use ES predefined users such as SYSAD (for starting and stopping ES regions) and schemaadmin (for MFDS administration), you will need to enable them. On your AD server, open the AD user manager (Active Directory Users and Computers) console. Select one or more users in the right pane, then choose Action > Enable Account from the main menu.

Parent topic: Final User Tasks


Disable Password Expiration for ES Users

The Microsoft user object class uses Windows passwords, which means normal Windows password rules in the domain security policy apply, including password expiration. Some administrators would prefer that the passwords for the predefined ES users (such as mfuser and SYSAD) not expire, since these are not normal login accounts. You can edit these users using standard Windows user administration tools and set the Password does not expire option for them.

Parent topic: Final User Tasks


Remove Predefined Users

Some administrators may choose to delete the predefined ES users after installation, and use only existing Windows user accounts for administering ES and signing on to MSS. We recommend doing this only after verifying basic ES operation with security enabled, since that will make it easier for Support to diagnose any problems.

You should not remove the default user accounts CICSUSER, JESUSER, IMSUSER, and mfuser, unless you specify different default accounts in the ES configuration (see the ES/MSS documentation for details). You can disable these accounts in Windows to prevent anyone from using them to log on to Windows.

If you remove the mf_cs and mf_mdsa users, you will not be able to run nonsecured ES servers using the default options.

Be sure you have another account for MFDS administration before removing the schemaadmin user.

Also, if you used CN=Users as your user container above, you can remove the empty CN=Enterprise Server Users container.

Parent topic: Final User Tasks


Configuring the Default ESMAC User

Setting the default ESMAC user

When starting a secure enterprise server region or instance, the system authenticates the credentials of a specific user ID when doing so. This user ID is known as the default ESMAC user, and has a setting of mfuser. You may change this user ID by setting the environment variable ES_USR_DFLT_ESMAC in the Directory Server (MFDS) in the [ES-Environment] tag in Configuration Information.

If you change the credentials of the default ESMAC user ID, then you must ensure that it has the correct privileges to start a region. Failure to set these privileges means that you will be unable to start a region. See Make the User an MSS System Administrator for more details.

Note: In legacy security only, creating an mfuser secures your enterprise servers.

Disabling the default ESMAC user

You can disable the ESMAC default user in order to increase the security of your region. To do this, set the environment variable ES_ESM_DISABLE_DFLTUSER_ESMAC in the Directory Server (MFDS) in the [ES-Environment] tag in Configuration Information. This disables the DEFAULT button on the logon screen so that users must always enter a valid userid and password.

Parent topic: Final User Tasks
Related tasks
Make the User an MSS System Administrator


Configure ES Security

To use the ES security information in LDAP, you will need to configure ES security:

  • Create one or more Security Managers to connect to your LDAP server. On the Add Security Manager page, you need to set various attributes for these managers:
    • From the Enterprise Server Administration home page, click Security on the left pane.

      This opens the Configure Security Options page.

    • On the Security Managers tab, click Add.

      This opens the Add Security Manager page.

    • Type a descriptive name in the Name field.
    • Type mldap_esm in the Module field.
    • Type the connection path and port number to your LDAP server in the Connection Path field.
      Note: ldap://servername or ldaps://servername to use an SSL-secured connection, if your LDAP client and server support SSL.
    • Type the credentials that the MLDAP ESM module requires to connect, in the Authorized ID and Password fields.

      The user should have read, write and modify access to the Enterprise Server user, group and resource objects in the LDAP repository.

    • The Cache limit parameter is currently ignored by the ESM Module.
    • The Cache TTL parameter is currently ignored by the ESM Module.
    • Type a description in the Description field.
    • In the Configuration Information field, add a number of directives to alter the default behaviour. Configure this for your particular LDAP repository. A typical configuration would be:
      [LDAP]
base=CN=Micro Focus,CN=Program Data,DC=somecorp,DC=com
user container=CN=user-container
group container=CN=group-container
resource container=CN=resource-container
[Verify]
Mode=MF-hash
    • Click Add.

      This adds the security manager to the Security Manager Pool.

  • Alter the security configuration for MF Directory Server, ES Default Security, and/or specific ES servers to use your new Security Manager

See MLDAP ESM Module for information on configuring the module to match your AD setup. Also, see Configuring the ESF LDAP Security Administration Web Interface for an example use of the configured security manager.

Parent topic: Preparing Active Directory for Enterprise Server Security
Related concepts
MLDAP ESM Module
Configuring the ESF LDAP Security Administration Web Interface


Configuring Windows Users as Enterprise Server Administrators

With this configuration:

  • Windows users are stored in Active Directory.
  • Enterprise Server uses Windows user authentication to authenticate administrators. You can restrict access to ES/MSS to a subset of Windows users by setting the appropriate ES/MSS resource permissions.

    Windows manages passwords (so Windows password policies will apply).

  • Enterprise Server administrators sign on with their Windows usernames and passwords
  • Other user attributes (for example operator class) are stored as additional attributes of the Windows user objects in AD.

For many installations, this provides the best of both worlds: mainframe-compatible security for Enterprise Server, but there is only one set of user accounts, and they're managed with standard Windows tools.

This configuration uses two ESM modules. Both use Active Directory, but through different interfaces, and they perform different tasks.

  • The OS ESM module processes user sign-on (Verify) requests by calling standard Windows APIs for user login and (if requested) password change. Windows handles these calls by communicating with the domain controller, which reads and updates Active Directory.
  • The MLDAP ESM module makes LDAP requests to AD to get user attributes and resource access control rules.

As with most ESF security configurations, this type can be used for some or all enterprise server instances and/or for MFDS.

  • Overview
  • Configuring ES and AD
Parent topic: Configuring Security using Active Directory


Overview

  • The OS ESM Module
  • The MLDAP ESM Module
  • The Security Manager Stack
  • Objects and Attributes in Active Directory
Parent topic: Configuring Windows Users as Enterprise Server Administrators


The OS ESM Module

The OS ESM module uses the Windows OS as an external security manager. It is quite simple, with only a handful of configuration options (for passtoken support), and it only supports ESF Verify (user signon) requests. It uses the Windows LogonUser function to check whether the user has supplied the correct password and is allowed to log into the system. Windows security policy rules such as restricted logon hours will be applied automatically, and if a user's password has expired and they have not supplied a new password, the request will be rejected with a must-change-password status. In other words, an MSS signon using this ESM will behave much like a conventional Windows login.

If the user requested a password change, the ESM module will call the Windows NetUserChangePassword function to attempt to change the password. Again, this is essentially the same as a conventional Windows login where the user specifies a new password.

Note that currently MSS restricts the length of usernames and passwords (see the ES documentation for details). Also, usernames or passwords that use non-ASCII characters may not work correctly.

Parent topic: Overview


The MLDAP ESM Module

The MLDAP ESM module lets you use an LDAP server as an external security manager. It is relatively full-featured and has a number of configuration options. By default, it implements ES security using LDAP object classes defined by Micro Focus; these objects are used only by ES, and not integrated with security for the OS or other applications.

However, the MLDAP ESM module can be configured to use other LDAP object classes (and containers, so it does not require the default directory hierarchy). By itself, this is not sufficient to completely integrate with Windows security, because the MLDAP ESM module cannot use Microsoft user password attributes; so if you used just the MLDAP ESM with Microsoft user classes, users would have separate passwords for Windows and MSS. In conjunction with the OS ESM, however, the MLDAP ESM will ignore the user password attribute (and other attributes used only for user signon) defined by Micro Focus, if the OS ESM has already verified the user using Windows.

Parent topic: Overview


The Security Manager Stack

An ESF configuration is defined (in MFDS) as one or more security managers, arranged in a list or stack. A security manager is an ESM module plus its configuration information, and a stack specifies which security managers will be used, and in what order they'll be called.

The configuration presented here will include a security manager using OS ESM and another manager using MLDAP ESM, configured to use the Microsoft user LDAP object class for users (rather than the default Micro Focus user class). These managers will be stacked so that the OS ESM is called first.

For Verify requests, ESF will call the OS ESM, which will use Windows to authenticate the user, as described above. Then (if the user is successfully verified) ESF will call the MLDAP ESM, which will load the user's MSS attributes from AD.

For Auth requests, ESF will only call the MLDAP ESM, since the OS ESM does not implement Auth. The MLDAP ESM will apply the access control rules defined in AD.

Parent topic: Overview


Objects and Attributes in Active Directory

With this configuration, ES will use a combination of Microsoft and Micro Focus object classes in Active Directory.

The Windows APIs invoked by OS ESM during Verify requests operate (indirectly) on the Windows security principals defined in AD. (More information on Windows security principals is available from the Microsoft Developer Network and similar resources.) These principals typically use LDAP object classes defined by Microsoft, such as user. Those classes have attributes such as cn (common name), which is the (base) username, and password, which contains the Microsoft hashed password.

In this configuration, the object class used for users will be extended to include attributes defined by Micro Focus. These attributes (which begin with "microfocus-MFDS-") are ignored by Windows, but ES will use them to set session characteristics when a user logs in, such as timeout and operator class. When a user signs on to MSS or MFDS, the MLDAP ESM will retrieve the values of those attributes from the user object.

Also during signon, the MLDAP ESM module will consult the ES user group lists. These are specified with microfocus-MFDS-User-Group objects, and they allow a user to belong to multiple MSS groups. Note that at this time ES does not use Windows user groups to control access to MFDS and MSS resources, even with this configuration.

Since OS ESM is handling the actual user credential verification, some of the attributes that Micro Focus defines for ES users are not used:

Unused Micro Focus User Attributes

Attribute Name | Description
microfocus-MFDS-User-Pwd | Micro Focus user password hash
microfocus-MFDS-User-Pwd-ExpirationDate | password expiration
microfocus-MFDS-User-Pwd-MustChange | password must-change flag
microfocus-MFDS-User-AllowLogon | allow-logon flag
microfocus-MFDS-User-ExpirationDate | user expiration
microfocus-MFDS-User-CreateToken | passtoken creation authority (if tokens are enabled in OS ESM)
microfocus-MFDS-User-UseToken | passtoken signon authority (if tokens are enabled in OS ESM)

Instead, the Windows password, expiration date, etc will be used. Note that the two passtoken attributes are used unless passtoken support is explicitly configured in OS ESM.

For resource access (Auth) requests, the MLDAP ESM will retrieve MF resource object access control data from microfocus-MFDS-Resource objects in AD.

Parent topic: Overview


Configuring ES and AD

This section describes one set of configuration options for ES and AD to enable integrated user accounts, with the same user information used for Windows and ES/MSS logins. Many other variations are possible, so you may want to adapt this to the needs of your installation.

  • Prerequisites
  • Active Directory
  • Restrictions
  • For More Information
Parent topic: Configuring Windows Users as Enterprise Server Administrators


Prerequisites

You will need a suitable user object class defined in your Active Directory schema. This can be any class that can be used to define Windows security principals. For this example, we will use the user class defined by Microsoft (in the LDIF file MS-user.ldf, included with Active Directory).

You will also need to have populated your Active Directory repository with some users. You may have already defined your Windows domain users in Active Directory, or you may want to define just a few users for a trial implementation.

You will need to have updated the Active Directory schema with the Micro Focus object class definitions for user groups and resource access rules, and created the containers for those objects. Generally, you will also want to have installed the user group and resource access definitions included with the default ES/MSS security configuration, which you can edit later to suit your requirements. Usually all of this is done by installing the default security configuration included with ES/MSS, which is contained in es_default_ldap.ldf and installed using the es-ldap-setup.cmd script. This script is provided as a sample, and may need to be modified for your installation, particularly if you are using the full Active Directory (rather than AD LDS) as your LDAP server for Enterprise Server.

The default configuration includes a number of built-in user accounts (CICSUSER, SYSAD, etc.). If you want to use the default configuration, you will need to add these users to Active Directory in a separate operation, as described below in the "Active Directory" section.

Parent topic: Configuring ES and AD


Active Directory

For this configuration, you will need to make the following changes to your Active Directory installation:

  1. Extend the Active Directory schema with definitions for the Micro Focus LDAP classes for user groups and resource access control rules.
  2. Add the object containers, user groups, and resource rules from the default Micro Focus LDAP security configuration to your Active Directory repository. (You can edit these later to meet your requirements.)
  3. Extend the Active Directory schema to add the ES/MSS user attributes to the user class (or whatever LDAP object class you use to define your Windows users).
  4. (Optional) Import the predefined MFDS and ES/MSS users from the default LDAP configuration into your AD repository.
  5. Set the MSS attributes for your Windows users as necessary.
  6. Add Windows users to the appropriate MSS groups.
  • Micro Focus User Groups and Resource Rules
  • Adding MSS User Attributes to the user Class
  • Importing MSS Users
  • Setting MSS User Attributes for Windows Users
  • Adding Windows Users to MSS Groups
  • Configuring Operating System Security: osesm
  • Configuring mldap_esm Security Manager for an LDAP
  • An ES Server Security Configuration
  • Testing
  • Default Server and MFDS Configuration
Parent topic: Configuring ES and AD


Micro Focus User Groups and Resource Rules

The first two steps are normally accomplished by running the es-ldap-setup.cmd command script, just as if you were using the default Micro Focus LDAP security configuration (with MSS users defined using the microfocus-MFDS-User class). See Setting Up Security with AD LDS for more information.

Parent topic: Active Directory


Adding MSS User Attributes to the user Class

To update the definition of the user class in the Active Directory schema with the MSS user attributes, you can import the LDIF file ms-user-plus-mto.ldf, which should have been included with this document. Typically, you'll use a command line like the following:

ldifde -i -f ms-user-plus-mto.ldf -k -v -j . -c "DC=X" #schemaNamingContext

(Specify this command all on one line.)

For those unfamiliar with the ldifde command, the parameter #schemaNamingContext is a symbolic constant that will be replaced with the DN of the schema in your LDAP directory. The parameter DC=X is a placeholder in the LDIF file that will be replaced with the value of #schemaNamingContext by ldifde as it processes the file. So where the LDIF commands in the file specify "DC=X", they will actually update the LDAP schema.

If you are using a class other than user for your Windows users, you'll have to modify this LDIF file before importing it. See your Active Directory documentation or other LDIF reference material for more information on LDIF files.

Parent topic: Active Directory


Importing MSS Users

If you want to use the predefined users from the default LDAP configuration supplied by Micro Focus, you can import the LDIF file mto-users.ldf, which should have been included with this document. Typically, you'll use a command line like the following:

ldifde -i -f mto-users.ldf -k -v -j . -c "DC=X" user-container

(Specify this command all on one line.) user-container should be the distinguished name (DN) of the LDAP container that holds your Windows users.

If you are using a class other than user for your Windows users, you'll have to modify this LDIF file before importing it. See your Active Directory documentation or other LDIF reference material for more information on LDIF files.

Parent topic: Active Directory


Setting MSS User Attributes for Windows Users

You may want to set MSS user attributes, such as operator class or MSS user timeout, for some of your Windows users. Currently, this must be done manually using an AD administrative tool such as ADSIEdit, or by writing and importing a custom LDIF file. The MSS user attributes are listed briefly below; see the product documentation for more information.

MSS User Attributes

Attribute Name | Description
microfocus-MFDS-UID | Micro Focus user unique identifier; currently unused
microfocus-MFDS-User-MTO-Priority | MSS user priority
microfocus-MFDS-User-MTO-Timeout | MSS user timeout
microfocus-MFDS-User-MTO-OperatorClass | MSS operator class
microfocus-MFDS-User-MTO-OperatorID | MSS operator ID
microfocus-MFDS-User-MTO-GroupPrefix | MSS group prefix
microfocus-MFDS-User-CustomText | MF custom text field; currently unused
microfocus-MFDS-User-DefaultGroup | MSS default group
microfocus-MFDS-User-UseToken | passtoken signon authority (if tokens are not enabled in OS ESM)
microfocus-MFDS-User-CreateToken | passtoken creation authority (if tokens are not enabled in OS ESM)

Micro Focus plans to provide additional tools to maintain MSS user attributes in future releases.

Parent topic: Active Directory


Adding Windows Users to MSS Groups

MSS resource access is typically controlled by rules that apply to user groups rather than to individual users, so you will probably want to add your Windows users to MSS user groups (SYSADM, etc) as appropriate. See the product documentation for more information about MSS user groups and how groups are used.

MSS user groups will be defined in the user group container that was created as part of the initial ES LDAP setup process. Usually this container is called "Enterprise Server User Groups".

Adding a user to a group is simply a matter of adding that user's common name (CN), which is the user's Windows login name (without any domain prefix or suffix), to the microfocus-MFDS-Group-Member attribute of the appropriate group. This is a multi-valued attribute, so it can have any number of user names specified for it. You will need to use an AD administration tool such as ADSIEdit or a custom LDIF file to make this change.

Once you have completed ES configuration, you may be able to use the MFDS user group administration screens to add or remove users from groups. (This depends on appropriate configuration in MFDS, appropriate permissions granted to the user account used by the ESM module, and other factors, so it may not work for all installations.)

Micro Focus plans to provide additional tools to maintain MSS user groups in future releases.

Parent topic: Active Directory


Configuring mldap_esm Security Manager for an LDAP

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, MSS user groups, and MSS resource access rules, 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
group container=group-container
resource container=resource-container
    DN-suffix | The common part of the DN for your user container, MSS group container, and MSS resource rules container. For example, if your users are in CN=users,DC=somecorp,DC=com, and your MSS containers are in CN=MF,DC=somecorp,DC=com, you could set base to DC=somecorp,DC=com.
    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
    group-container | The DN of the container for MSS user group objects, without the "base" suffix, for example: CN=Enterprise Server Groups,CN=MF
    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: Active Directory
Parent topic: Configuring Security Using OpenLDAP
Related concepts
Configuring the ESF LDAP Security Administration Web Interface


An ES Server Security Configuration

Now you need to create a security configuration for an Enterprise Server region to test the security managers and LDAP installation. You can use the "Default ES Security" configuration for this, but you may wish to set this security configuration just for a single test server initially.

To create the default ES security configuration, which will be used for all ES servers defined by that MFDS that do not have an individual security configuration, go to the "Default ES Security" tab under Configure Security Options. To create a security configuration for just one server, edit that server and select the "Security" tab, then uncheck the "Use default ES Security Manager configuration" option.

Your security configuration will specify the Security Managers you created in the previous two steps, with the OS ESM manager first:

To create this configuration, uncheck Use default ES Security Manager configuration (if it is checked) and click Apply. Then click the Add... button under Security Manager List to get the list of security managers. Choose the security manager you just defined for OS ESM (we called it "Windows" above) and click Add. Repeat the process to add the security manager you just defined for MLDAP ESM (called "Active Directory" in the previous step).

Make sure that the OS ESM manager is first in the list. If the security managers end up in the wrong order, use the down-arrow button to the right of the list to switch them.

Set any additional options that are appropriate for your requirements. See the Enterprise Server Security documentation for details.

Click OK to save the security configuration.

Parent topic: Active Directory


Testing

To test the security configuration, try to start the ES server you just configured. If it fails to start, look for errors in your MLDAP ESM Security Manager configuration, which is the most likely source of trouble.

When the server starts, try to sign on to CICS or ESMAC with your Windows username and password. You should also be able to change your password from those signon screens. (Remember that you will be changing your Windows domain password!)

You may also want to test resource access control. For example, the CICS transaction CENV should be available to all users (assuming the default ES/MSS security configuration rules are being used), but the CINQ transaction is only available to members of the OPERATOR and SYSADM groups. So with two test users (or one user that signs on using different signon groups, if you are not using the "Use all groups" option), you can confirm whether group permissions are being applied correctly.

Parent topic: Active Directory


Default Server and MFDS Configuration

Once you are satisfied with your security configuration, you may want to make it the default configuration for all ES servers (if it isn't already), or make it the security configuration for MFDS as well.

To make it the default ES security configuration, go to the Security options in MFDS, then to the Default ES Security tab, and follow the instructions listed above for creating the security configuration.

To make it the MFDS security configuration, you can either do the same on the MF Directory Server security tab, or, if you have made it the default ES security configuration, go to that tab and select the Use default ES Security Manager List option. Note that MFDS security is somewhat more complex than ES security, and consequently you're more likely to run into configuration issues with MFDS.

Parent topic: Active Directory


Restrictions

There are some restrictions that may affect your use of Enterprise Server Security with Active Directory.

  • MSS User Migration
  • User Administration with MFDS
  • User Search Order
  • Windows Groups Not Used by ESF
Parent topic: Configuring ES and AD


MSS User Migration

This release of ES does not include a tool for migrating existing MSS users, defined in the Resource Definition (RDO) file dfhdrdat, to LDAP user classes other than microfocus-MFDS-User. The cas-to-ad tool that is used by es-ldap-setup can only create Micro Focus user objects.

If you have a significant number of MSS users (who are not already Windows users) to migrate, you may want to use the casrdtex utility to export the RDO definitions to a text file, which could be processed into an LDIF file using a scripting language such as Perl.

Parent topic: Restrictions


User Administration with MFDS

MFDS includes some administration capabilities for LDAP external security managers, if it is configured appropriately. (MFDS must be using the Security Manager in question for its security, and the ESM must be configured with a user ID that has update authority for the LDAP objects. See the MFDS documentation for more information.)

With the configuration described in the section Configuring Windows Users as Enterprise Server Administrators, MFDS can usually be used to administer MSS user groups and resource access definitions. Also, some user administration operations will succeed. However, other operations, such as changing the user's password, will either fail or have no effect, because they will update one of the user attributes which are not used in this configuration.

Parent topic: Restrictions
Related information
Configuring Active Directory Users as Enterprise Server Administrators


User Search Order

The OS ESM module uses the Windows LogonUser function to verify a user's credentials (username and password), in the following manner:

  1. Try LogonUser with the username and password, and the domain parameter set to ".", which means to search the local system.
  2. If that fails, call LookupAccountName to try to find the domain in which the user is defined. According to Microsoft's documentation, this will first search well-known names, then local accounts, then the primary domain, then other trusted domains, and then (for Windows 2000 and later) the domain forest.
  3. If LookupAccountName succeeds, try LogonUser again with the domain returned by LookupAccountName.

If a user is defined in multiple places on that search list, the OS ESM module only tries to authenticate the user in the first one it finds. Normally this will have the expected behavior (much like logging on to Windows conventionally), but in a complex domain configuration situation it could produce confusing results.

The initial domain to search can be changed from "." to any single domain name with this setting in the configuration text area for the Security Manager:

[Operation]
Domain=name
Parent topic: Restrictions


Windows Groups Not Used by ESF

ESF does not make any use of Windows user groups. All group-related resource access control is performed using MSS user groups.

However, Windows security policies that contain group rules affecting user login, such as restricting logins to particular hours of the day, affect users in those groups, just as they do for Windows login.

Parent topic: Restrictions


For More Information

For additional information about Active Directory or LDAP, consult your Microsoft documentation.

If you have questions, please contact Micro Focus Support.

Parent topic: Configuring ES and AD


Configuring Active Directory Users as Enterprise Server Administrators

With this configuration:

  • Windows users are stored in Active Directory, but Enterprise Server does not use Windows user authentication to authenticate administrators. You maintain user information and Enterprise Server administrator passwords using your LDAP management software.
  • Other user attributes (for example operator class) are stored as additional attributes of the Windows user objects in AD
Note: The content in this topic assumes that you have read the previous content, and are familiar with Active Directory and LDAPs.
  • Prerequisites
  • Giving a User ES Administration Authority
  • Create ES Security Managers
  • Setting the Default ES and MFDS Security Configuration
  • Verify the Security Configuration
Parent topic: Configuring Security using Active Directory
Related information
User Administration with MFDS


Prerequisites

Software

The following software is required to perform these procedures:

  • ADSIEdit.msc, the Microsoft AD management console that is shipped with AD LDS. You can run this from the Start menu or from the command line.

Information

You will need the following information:

  • A user account authorized to make AD schema changes (shown as AD-admin and AD-password below).
  • The user account in the domain controlled by your AD server that you will be granting ES administrative authority.

    To simplify the process we recommend that this account have a name that is no longer than eight characters, ASCII, and has no spaces; and that the account's "Common name" (the name that appears in the list of users on the domain controller, in the Active Directory Users and Computers console) be the same as its "Logon name" (shown in the Account tab of the user's Properties in Users and Computers). Also, you may run into problems if this account exists both on the domain and the local computer, with the same name but with different passwords.

    This account is shown as ES-admin and ES-password below.

  • The location of the AD server (shown as servername below).
  • The DN of the AD domain (shown as domain-DN below). Normally, this will be the fully-qualified domain name of the AD host, minus the hostname, with each segment of the name listed as a separate DC element, so for example server.dept.mydom.com would use:

    DC=dept,DC=mydom,DC=com

Preparation

This procedure assumes that you have already:

  • Configured your Active Directory schema and repository for ES LDAP-based security.
  • Installed an Enterprise Server product on at least one system.
Parent topic: Configuring Active Directory Users as Enterprise Server Administrators


Giving a User ES Administration Authority

  • Start ADSI Edit
  • Connect to Active Directory
  • Make the User an MSS System Administrator
Parent topic: Configuring Active Directory Users as Enterprise Server Administrators


Start ADSI Edit

The ADSI Edit management console lets you modify objects in the AD repository. You can use other LDAP tools to make these changes - for example, you can create LDIF files and use the ldifde utility to import them, which is useful for making changes in bulk - but this example uses ADSIEdit.

Run Start > Administrative Tools > ADSI Edit.

Parent topic: Giving a User ES Administration Authority


Connect to Active Directory

  1. In the left pane, select ADSI Edit.
  2. From the menu, select Action > Connect to...
  3. Enter the servername (the hostname of your AD server) for the connection name and server name. Select Distinguished name (DN) or naming context and enter the domain-DN. This is similar to: DC=dept,DC=mydom,DC=com Set the authorized user name and password to AD-admin and AD-password if you're not already logged on as that user.
Parent topic: Giving a User ES Administration Authority


Make the User an MSS System Administrator

  1. In the left pane, open your new connection and the folder inside it, then select the CN=Users folder, which contains your domain's users.
  2. In the right pane, select the user you want to modify (CN=ES-Admin).
  3. Choose Action > Properties.
  4. Widen the Attribute column so you can read the full name of each attribute. Scroll down to find the microfocus-MFDS-User-DefaultGroup attribute and double-click it.
  5. Set the attribute's value to SYSADM. This sets the MSS default group for the user; the SYSADM group has permission to start ES and so forth in the default ES LDAP security configuration. Click OK and close the Properties window.
Parent topic: Giving a User ES Administration Authority
Related concepts
Configuring the Default ESMAC User


Create ES Security Managers

  • MFDS Security Configuration Screen
  • LDAP Security Manager
Parent topic: Configuring Active Directory Users as Enterprise Server Administrators


MFDS Security Configuration Screen

Open a browser window and connect to http://es-host:86, where es-host is the hostname of the system running your COBOL development system.

On the left-side menu, click on Security.

Parent topic: Create ES Security Managers


LDAP Security Manager

You will need to create a security manager to get security rules from AD over LDAP, using the MLDAP ESM Module:

  1. Select the Security tab and click Add.
  2. Enter the following information:
    Fieldname | Contents
    Name | LDAP
    Module Name | mldap_esm
    Connection Path | The servername
    Authorized ID cn=AD-admin,cn=users,domain-DN, for example:

    cn=administrator,cn=users,DC=dept,DC=mydom,DC=com

    Password | AD-password
  3. In the Configuration Information field, type a number of directives to alter the default behaviour. Configure this for your particular LDAP repository. A typical configuration based on the sample configuration would be:
    [LDAP]
base=[domain DN]
user class=user
user container=CN=Users
group container=CN=Enterprise Server User Groups,
  CN=Micro Focus,CN=Program Data
resource container=CN=Enterprise Server Resources,
  CN=Micro Focus,CN=Program Data

[Verify]
mode=bind
password type=AD
  4. Click Add

Note that in a production environment you would not want to use your AD administrative ID for the security manager, since that would create a security risk. It is shown only for convenience here.

In production, you would use an ID that had only the necessary permission for the repository, based on your intended use. (Basic ES security functions only need read access to the user information and the folders under cn=Micro Focus,cn=Program Data. If you want to use MFDS to administer ES groups and resources under LDAP, you have to use an account that also has write permission to the MF program data objects.)

Parent topic: Create ES Security Managers


Setting the Default ES and MFDS Security Configuration

You use the Enterprise Server Administration user interface to perform these procedures.

  • Set the Default ES Security Configuration
  • Setting the MFDS Security Configuration
Parent topic: Configuring Active Directory Users as Enterprise Server Administrators


Set the Default ES Security Configuration

Set the Default ES Security Configuration to use your new security manager(s), so you can use your ES administrative ID to perform CAS functions such as starting and stopping an ES region.
  1. In the left panel, select Security.
  2. Select the Default ES Security tab.
  3. Click Add to add a security manager.
  4. Add your new security manager(s):
    1. Select LDAP and click Add.

      The Default ES Security tab should now show LDAP.

  5. Click Apply.
Parent topic: Setting the Default ES and MFDS Security Configuration


Setting the MFDS Security Configuration

Next, configure MFDS 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 MFDS security configuration. If you don't want to change the MFDS security configuration now, you can add that user to MFDS directly by editing the MFDS Internal Security security manager and clicking on Properties.

To use the same security configuration for ES regions and MFDS:

  • Return to the MFDS Security Options page if necessary, and select the MF Directory Server tab.
  • Check the Use default ES Security Manager List checkbox.
  • Click Apply. The MF Directory Server tab should now show the same security manager(s) as Default ES Security.
Parent topic: Setting the Default ES and MFDS Security Configuration


Verify the Security Configuration

The topics in this section describe how you can check that your Active Directory is configured correctly.

  • Verify that the ESDEMO Server Starts
  • Verify MFDS Restricted Access
Parent topic: Configuring Active Directory Users as Enterprise Server Administrators


Verify that the ESDEMO Server Starts

Go to an Enterprise Developer command prompt and try to start ESDEMO:

casstart /uES-admin /pES-password

where ES-admin and ES-password are the username and password of the user you edited in step 4 to grant ES administration permissions. (You can also start ESDEMO from MFDS and supply a username and password in the Use Enterprise Server credentials form, but this is easier to run again if you need to correct a typo or other problem.)

ESDEMO should start successfully. If it does not, here are some things to check:
  • ES-admin and ES-password are spelled correctly.
  • The ESDEMO console log (console.log) shows the MLDAP ESM module being loaded and initialized successfully. The location of the console log depends on your installation, but the default location is %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\ESDEMO.
    • If the MLDAP ESM module fails to initialize because it can't connect to the server, check the Connection Path setting in the LDAP security manager in MFDS. Also check firewall configurations on both systems.
    • If the MLDAP ESM module cannot bind to the server, check the Authorized ID and Password settings in the LDAP security manager in MFDS.
    • If the MLDAP ESM module is logging other errors, check the text in the Configuration Information area in the LDAP security manager in MFDS, such as the DNs of the various containers. Errors here will prevent the ESM module from finding its data in AD.
  • The user's "common name" does not match the user's "logon name". A user in Active Directory has multiple names, which can be confusing. Users log on to Windows using the "logon name", which is normally a fairly short nickname (such as the user's initials). If you look at a user's properties in Active Directory, this name is shown on the Account tab.

    LDAP clients, such as the MLDAP ESM module, use a user's Distinguished Name (DN), which is formed using the user's Common Name (CN), and the Common Name is set by Windows when the user is created. By default, Windows sets the common name to the user's first name, middle initial, and last name.

    Since the MLDAP ESM only uses the common name, it doesn't matter if the logon name is different, but users might be confused if they can log on using their common name but not their logon name. Also, if the common name is longer than 8 characters or contains spaces, that may cause difficulties with the current version of ES. (Future ES versions will support long names better.)

    You can change a user's common name by renaming the user in Active Directory Users and Computers. After you rename the user, you can go back and reset the user's first and last name and display name (under the General tab of the Properties dialog), if you wish.

Parent topic: Verify the Security Configuration


Verify MFDS Restricted Access

Once ESDEMO starts successfully, you can try enabling restricted access in MFDS to validate your security configuration there. Return to your MFDS browser session and:

  1. On the left-side menu, click on Security.
  2. Select the MF Directory Server tab.
  3. Check the Restrict administration access checkbox.
  4. Click Apply.
  5. MFDS will prompt you to supply a username and password that are authorized under the existing security configuration (to authorize the change to a new security configuration). If you still have the predefined security configuration that's installed with the product, you can use schemaadmin here for the username and password.
  6. MFDS will prompt you to supply a username and password that are authorized under the new security configuration (to prevent you from locking yourself out). Enter your ES-admin user ID and its password.
  7. If this works, you'll be sent to the MFDS restricted-functionality home page. Click on Log On and try your ES-admin ID.
Parent topic: Verify the Security Configuration


Configuring Security Using OpenLDAP

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

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

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

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 )
       MAY ( description ) )
    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

  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

  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

  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

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


Examples

This section contains examples of using LDIF to define Enterprise Server security information in Active Directory.

  • Examples of RACF Commands Compared with Active Directory Definitions
  • Defining a User with LDIF
  • Defining a Group with LDIF
  • Defining CAS Resources with LDIF
  • Defining Files with LDIF
  • Defining the SURROGAT Class and Users with LDIF
  • Defining a CICS Transaction with LDIF
Parent topic: Securing an Enterprise Server Installation


Examples of RACF Commands Compared with Active Directory Definitions

  • FCT Control: RACF Command and AD Definition
  • DCT Control: RACF Command and AD Definition
  • JCT Control: RACF Command and AD Definition
  • DOCTEMPLATE Control: RACF Command and AD Definition
  • EXEC CICS START control: RACF Command and AD Definition
  • EXEC CICS LINK/XCTL/LOAD control: RACF Command and AD Definition
  • EXEC CICS SET/INQUIRE/ENABLE/DISABLE control: RACF Command and AD Definition
  • CAS Commands control: RACF Command and AD Definition
Parent topic: Examples


FCT Control: RACF Command and AD Definition

FCT control: RACF command

RDEFINE FCICSFCT (file1, file2, .., filen)
  UACC(NONE)

  NOTIFY(sys_admin_userid)
  PERMIT file1 CLASS(FCICSFCT) ID(group1, group2) ACCESS(UPDATE)
  PERMIT file2 CLASS(FCICSFCT) ID(group1, group2) ACCESS(READ)
Default CICS CLASS used: FCICSFCT

Parameters passed to ESM:

  Entity: File ID
  Facility: Terminal
  Transaction active

FCT control: Active Directory ldif

dn: CN=FCICSFCT,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local

changetype: add
  objectClass: top
  objectClass: container
  description: CICS Class for FCT
dn: CN=FILESAF,CN=FCICSFCT,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local

changetype: delete
dn: CN=FILESAF,CN=FCICSFCT,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local

changetype: add
  objectClass: microfocus-MFDS-Resource
  microfocus-MFDS-Resource-Class: FCICSFCT
  microfocus-MFDS-Resource-ACE: allow:SAFU:update
  microfocus-MFDS-Resource-ACE: allow:PLTPISUR:update
  microfocus-MFDS-Resource-ACE: allow:SYSADM
  group:update
  microfocus-MFDS-Resource-ACE: allow:OPERATOR
  group:update
  microfocus-MFDS-Resource-ACE: deny:*:execute
  microfocus-MFDS-UID: mfuid
  description: FILE used by test
Parent topic: Examples of RACF Commands Compared with Active Directory Definitions


DCT Control: RACF Command and AD Definition

DCT control: RACF command

RDEFINE  DCICSDCT  (qid1, qid2, ..., qidn) UACC(NONE)
                   NOTIFY(sys_admin_userid)
PERMIT qid1 CLASS(DCICSDCT) ID(group1, group2) ACCESS(UPDATE)
PERMIT qid2 CLASS(DCICSDCT) ID(group1, group2) ACCESS(UPDATE)

Default CICS CLASS used: DCICSDCT

Parameters passed to ESM:

          Entity: DCT queue ID
          Facility: Terminal
          Transaction active

DCT control: Active Directory ldif

dn: CN=DCICSDCT,CN=Enterprise
  Server Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: add
  objectClass: top
  objectClass: container
  description: CICS Class for DCT

  dn: CN=STDQ,CN=DCICSDCT,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: delete

  dn: CN=STDQ,CN=DCICSDCT,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: add
  objectClass: microfocus-MFDS-Resource
  microfocus-MFDS-Resource-Class: DCICSDCT
  microfocus-MFDS-Resource-ACE: allow:SAFU:update
  microfocus-MFDS-Resource-ACE: deny:*:execute
  microfocus-MFDS-UID: mfuid
  description: TDQ used by test
Parent topic: Examples of RACF Commands Compared with Active Directory Definitions


JCT Control: RACF Command and AD Definition

JCT control: RACF command

RDEFINE  KCICSJCT  userjnls UACC(NONE)
                   ADDMEM(JRNL001, JRNL002, ....)
                   NOTIFY(sys_admin_userid)
PERMIT   userjnls  CLASS(KCICSJCT) ID(group_userid)
             ACCESS(UPDATE)

Default CICS CLASS used: JCICSJCT

Parameters passed to ESM:

  Entity: JCT ID
  Facility: Terminal
  Transaction active

JCT control: Active Directory ldif

dn: CN=JCICSJCT,CN=Enterprise
  Server Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: add
  objectClass: top
  objectClass: container
  description: CICS Class for JCT

  dn: CN=01,CN=JCICSJCT,CN=Enterprise Server Resources,
    CN=Micro Focus,CN=Program Data,DC=local
  changetype: delete

  dn: CN=01,CN=JCICSJCT,CN=Enterprise Server Resources,
    CN=Micro Focus,CN=Program Data,DC=local
  changetype: add
  objectClass: microfocus-MFDS-Resource
  microfocus-MFDS-Resource-Class: JCICSJCT
  microfocus-MFDS-Resource-ACE: allow:SAFU:control
  microfocus-MFDS-Resource-ACE: deny:*:execute
  microfocus-MFDS-UID: mfuid
  description: JOURNAL used by test
Parent topic: Examples of RACF Commands Compared with Active Directory Definitions


DOCTEMPLATE Control: RACF Command and AD Definition

DOCTEMPLATE control: RACF command

RDEFINE RCICSRES (DOCTEMPLATE.doc1, DOCTEMPLATE.doc2, .., DOCTEMPLATE.docn)
                  UACC(NONE)
                  NOTIFY(sys_admin_userid)
PERMIT  DOCTEMPLATE.doc1
        CLASS(RCICSRES)
        ID(group1, group2)
        ACCESS(READ)

DOCTEMPLATE control: Active Directory ldif

dn: CN=*,CN=RCICSRES,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=mftesting,DC=com
changetype: delete

dn: CN=*,CN=RCICSRES,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=mftesting,DC=com
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: MFESMAC
microfocus-MFDS-Resource-ACE: allow:SYSAD:alter
microfocus-MFDS-Resource-ACE: allow:ESMAC:alter
microfocus-MFDS-Resource-ACE: allow:CICSUSER:read
microfocus-MFDS-Resource-ACE: deny:*:execute
microfocus-MFDS-UID: mfuid
description: Allow full access any URIMAP to SYSAD or ESMAC Users
Parent topic: Examples of RACF Commands Compared with Active Directory Definitions


EXEC CICS START control: RACF Command and AD Definition

EXEC CICS START control: RACF command

RDEFINE  ACICSPCT (tran1, tran2, ..., trann) UACC(NONE)
                  NOTIFY(sys_admin_userid)
PERMIT  tran1 CLASS(ACICSPCT)  ID(userid) ACCESS(READ)
PERMIT  tran2 CLASS(ACICSPCT)  ID(userid) ACCESS(READ)
  • TCICSTRN if a terminal is used on the EXEC CICS START
  • ACICSPCT if no terminal is used on the EXEC CICS START
  • SURROGAT if a user is specified on the EXEC CICS START
  • For TCICSTRN and ACICSPCT

    Entity: Transaction ID

    Facility: Terminal

  • For SURROGAT

    Entity: Surrogate Userid

    Entity-1-ptr: Surrogate ACEE

    Facility: Terminal

EXEC CICS START control: Active Directory ldif

dn: CN=ACICSPCT,CN=Enterprise Server
Resources,CN=Micro Focus,CN=Program Data,DC=local
changetype: add
objectClass: top
objectClass: container
description: CICS Class for started transactions
dn: CN=TCICSTRN,CN=Enterprise Server
Resources,CN=Micro Focus,CN=Program Data,DC=local
changetype: add
objectClass: top
objectClass: container
description: CICS Class for TRANSACTIONS
dn: CN=SSST,CN=ACICSPCT,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local
changetype: delete
dn: CN=SSST,CN=ACICSPCT,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local
changetype: add objectClass:
microfocus-MFDS-Resource microfocus-MFDS-Resource-Class: ACICSPCT
microfocus-MFDS-Resource-ACE: allow:SAFU:read
microfocus-MFDS-Resource-ACE:
allow:SAFUSUR:read
microfocus-MFDS-Resource-ACE: deny:*:execute
microfocus-MFDS-UID: mfuid
description: CICS START with SURROGAT
dn: CN=SAFT,CN=TCICSTRN,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local
changetype: delete
dn: CN=SAFT,CN=TCICSTRN,CN=Enterprise Server
Resources,CN=Micro Focus,CN=Program Data,DC=local
changetype: add
objectClass:
microfocus-MFDS-Resource microfocus-MFDS-Resource-Class: TCICSTRN
microfocus-MFDS-Resource-ACE: allow:SAFU:read
microfocus-MFDS-Resource-ACE:
deny:*:
execute
microfocus-MFDS-UID: mfuid description:
Transaction used by test
Parent topic: Examples of RACF Commands Compared with Active Directory Definitions


EXEC CICS LINK/XCTL/LOAD control: RACF Command and AD Definition

EXEC CICS LINK/XCTL/LOAD control: RACF command

RDEFINE  MCICSPPT  (prog1, prog2, ..., progn)  UACC(NONE)
                  NOTIFY(sys_admin_userid)
PERMIT  prog1 CLASS(MCICSPPT)  ID(userid) ACCESS(READ)
PERMIT  prog2 CLASS(MCICSPPT)  ID(userid) ACCESS(READ)

Default CICS CLASS used: MCICSPPT

Parameters passed to ESM:

  • Entity: Program Name
  • Facility: Terminal
  • Transaction active

EXEC CICS LINK/XCTL/LOAD control: Active Directory ldif

dn: CN=MCICSPPT,CN=Enterprise
  Server Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: add
  objectClass: top
  objectClass: container
  description: CICS Class for PPT

  dn: CN=SAFLINK,CN=MCICSPPT,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: delete

  dn: CN=SAFLINK,CN=MCICSPPT,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: add
  objectClass: microfocus-MFDS-Resource
  microfocus-MFDS-Resource-Class: MCICSPPT
  microfocus-MFDS-Resource-ACE: allow:SAFU:control
  microfocus-MFDS-Resource-ACE: deny:*:execute
  microfocus-MFDS-UID: mfuid
  description: Program to test LINK
Parent topic: Examples of RACF Commands Compared with Active Directory Definitions


EXEC CICS SET/INQUIRE/ENABLE/DISABLE control: RACF Command and AD Definition

EXEC CICS SET/INQUIRE/ENABLE/DISABLE control: RACF command

RDEFINE  CCICSCMD CMDSAMP UACC(NONE)
                   NOTIFY(sys_admin_userid)
                  ADDMEM(AUTINSTMODEL, AUTOINSTALL, CONNECTION,
                  DSNAME, TRANSACTION, TRANDUMPCODE, VTAM)
PERMIT CMDSAMP CLASS(VCICSCMD) ID(operator_group) ACCESS(READ)
Default CICS CLASS used: CCICSCMD
  Parameters passed to ESM:

  Entity: Resource name

  Facility: Terminal

  Transaction active
  Resource Name can be:
  'PROCESSTYPE'.
  'LINE'.
  'MVSTCB'.
  'LSRPOOL'.
  'MAPSET'.
  'PARTITIONSET'.
  'SESSIONS'.
  'TYPETERM'.
  'EXITPROGRAM'.
  'JOURNALMODEL'.
  'REQID'.
  'TRACEDEST'.
  'TRACEFLAG'.
  'TRACETYPE'.
  'TSQUEUE'.
  'AUTINSTMODEL'.
  'AUTOINSTALL'.
  'BRFACILITY'.
  'CLASSCACHE'.
  'CONNECTION'.
  'CORBASERVER'.
  'DB2CONN'.
  'DB2ENTRY'.
  'DB2TRAN'.
  'DELETSHIPPED'.
  'DISPATCHER'.
  'DJAR'.
  'DOCTEMPLATE'.
  'DSNAME'.
  'DUMPDS'.
  'ENQMODEL'.
  'EXCI'.
  'FILE'.
  'IRC'.
  'JOURNALNAME'.
  'JVM'.
  'JVMPOOL'.
  'JVMPROFILE'.
  'MODENAME'.
  'MONITOR'.
  'PARTNER'.
  'PROFILE'.
  'PROGRAM'.
  'REQUESTMODEL'.
  'STATISTICS'.
  'STORAGE'.
  'STREAMNAME'.
  'SYSDUMPCODE'.
  'SYSTEM'.
  'TASK'.
  'TCLASS'.
  'TCPIP'.
  'TCPIPSERVICE'.
  'TDQUEUE'.
  'TERMINAL'.
  'TRANDUMPCODE'.
  'TRANSACTION'.
  'TSMODEL'.
  'TSPOOL'.
  'TSQNAME'.
  'UOW'.
  'UOWDSNFAIL'.
  'UOWENQ'.
  'UOWLINK'.
  'VTAM'.
  'WEB'.
  'WORKREQUEST'.
  'DUMP'.
  'RESETTIME'.
  'FEPIRESOURCE'.
  'BEAN'.
  'CFDTPOOL'.
  'RRMS'.
  'SUBPOOL'.
  'SECURITY'.
  'SHUTDOWN'.
  'UNKNOWN'.

EXEC CICS SET/INQUIRE/ENABLE/DISABLE control: Active Directory ldif

dn: CN=CCICSCMD,CN=Enterprise
  Server Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: add
  objectClass: top
  objectClass: container
  description: CICS Class for CMDS

  dn: CN=PROGRAM,CN=CCICSCMD,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: delete

  dn: CN=PROGRAM,CN=CCICSCMD,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: add
  objectClass: microfocus-MFDS-Resource
  microfocus-MFDS-Resource-Class: CCICSCMD
  microfocus-MFDS-Resource-ACE: allow:PLTPISUR:control
  microfocus-MFDS-Resource-ACE: allow:SAFU:control
  microfocus-MFDS-Resource-ACE: allow:SYSADM
  group:control
  microfocus-MFDS-Resource-ACE: deny:*:execute
  microfocus-MFDS-UID: mfuid
  description: PROGRAM entity for EXEC CICS SET/ENABLE/DISABLE commands

  dn: CN=EXITPROGRAM,CN=CCICSCMD,CN=Enterprise Server
  Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: delete

  dn: CN=EXITPROGRAM,CN=CCICSCMD,CN=Enterprise Server
  Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: add
  objectClass: microfocus-MFDS-Resource
  microfocus-MFDS-Resource-Class: CCICSCMD
  microfocus-MFDS-Resource-ACE: allow:PLTPISUR:control
  microfocus-MFDS-Resource-ACE: allow:SAFU:control
  microfocus-MFDS-Resource-ACE: allow:SYSADM
  group:control
  microfocus-MFDS-Resource-ACE: deny:*:execute
  microfocus-MFDS-UID: mfuid
  description: EXITPROGRAM entity for EXEC CICS SET/ENABLE/DISABLE commands

  dn: CN=TRANSACTION,CN=CCICSCMD,CN=Enterprise Server
  Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: delete

  dn: CN=TRANSACTION,CN=CCICSCMD,CN=Enterprise Server
  Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: add
  objectClass: microfocus-MFDS-Resource
  microfocus-MFDS-Resource-Class: CCICSCMD
  microfocus-MFDS-Resource-ACE: allow:PLTPISUR:control
  microfocus-MFDS-Resource-ACE: allow:SAFU:control
  microfocus-MFDS-Resource-ACE: allow:SYSADM
  group:control
  microfocus-MFDS-Resource-ACE: deny:*:execute
  microfocus-MFDS-UID: mfuid
  description: TRANSACTION entity
Parent topic: Examples of RACF Commands Compared with Active Directory Definitions


CAS Commands control: RACF Command and AD Definition

CASSTART/CASSTOP/CASFILE/CASSUB/CASOUT Commands control: RACF command

  • CLASS used:

    OPERCMDS Parameters passed to ESM:

  • Entity:

    Command (casstart/casstop/casfile/cassub/casout)

CASSTART/CASSTOP/CASFILE/CASSUB/CASOUT Commands control: Active Directory ldif

dn: CN=OPERCMDS,CN=Enterprise
  Server Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: add
  objectClass: top
  objectClass: container
  description: CICS Class for casstart/casstop/casfile....

  dn: CN=casstart,CN=OPERCMDS,CN=Enterprise
  Server Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: delete

  dn: CN=casstart,CN=OPERCMDS,CN=Enterprise
  Server Resources,CN=Micro Focus,CN=Program Data,DC=local
  changetype: add
  objectClass: microfocus-MFDS-Resource
  microfocus-MFDS-Resource-Class: OPERCMDS
  microfocus-MFDS-Resource-ACE: allow:SAFU:alter
  microfocus-MFDS-Resource-ACE: allow:SYSAD:alter
  microfocus-MFDS-Resource-ACE: allow:SYSADM
  group:alter
  microfocus-MFDS-Resource-ACE: deny:*:execute
  microfocus-MFDS-UID: mfuid
  description: casstart users
Parent topic: Examples of RACF Commands Compared with Active Directory Definitions


Defining a User with LDIF

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 or CESN
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

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: group AUDITORS | Groups can now be included in other groups. All the members of the AUDITORS group will also belong to the PAYROLL group. Be sure to use the group keyword when specifying a group member.
Parent topic: Examples


Defining CAS Resources with LDIF

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

Command | Description
dn: CN=DATASET,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies resource DATASET
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=**EZACONFG,CN=DATASET,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies the entity. CICS will use the physical filename when calling AUTH, if you do not want to specify the path, you can use '**' in front of the file, meaning any characters.
changetype: delete | action set to delete, we remove any existing definition
 | You must leave a blank line between actions
dn: CN=**EZACONFG,CN=DATASET,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
description: EZASOKET Configuration file | description of the resource
Parent topic: Examples


Defining the SURROGAT Class and Users with LDIF

Command | Description
dn : CN=SURROGAT,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies the SURROGAT 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 CICS SURROGATE users. JES Class for controlling access to job submission by surrogates. | description
 | You must leave a blank line between actions
dn : CN=PLTPISUR,CN=SURROGAT,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=PLTPISUR,CN=SURROGAT,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: SURROGAT | name of the class that the entity belongs to
microfocus -MFDS-Resource-ACE: allow:SYSAD:read | Terminology definition, we allow SYSAD to be a surrogat user of PLTPISUR
microfocus -MFDS-Resource-ACE: deny:*:execute | Terminology definition, we deny everyone else
microfocus -MFDS-UID: no | UID (Unique Identifier). use mfuid as the value
description: SAF SURROGAT user for PLTPI. Add all users that can start ES to it | description
Parent topic: Examples


Defining a CICS Transaction with LDIF

Command | Description
dn: CN=TCICSTRN,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies the TCICSTRN resource
changetype: add | action set to add, will create the resource
objectClass: top | this is a main class
objectClass: container | will contain entities
description: CICS transactions, normal attach security | description
 | You must leave a blank line between actions
dn: CN=TRN1,CN=TCICSTRN,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies the TRN1 entity
changetype: delete | action set to delete, will delete the entity
 | You must leave a blank line between actions
dn: CN=TRN1,CN=TCICSTRN,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies the TRN1 entity
changetype: add | action set to add, will create the entity
objectClass: microfocus-MFDS-Resource | We are creating a resource
microfocus-MFDS-Resource-Class: TCICSTRN | name of the class that the entity belongs to
microfocus-MFDS-Resource-ACE: allow:ALLUSER group:read | Terminology definition, we grant anyone from group ALLUSER read access
microfocus-MFDS-Resource-ACE: deny:*:execute | Terminology definition, we deny everyone else
microfocus-MFDS-UID: no | UID (Unique Identifier). use mfuid as the value
description: My first Transaction | description
Parent topic: Examples


Managing LDAP Security Manager from the Enterprise Server UI

You use the mldap_esm security manager to configure an LDAP server 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.

The ESF administration facility makes some security checks before it attempts to process an administration request:

  1. It requires the user be successfully signed into ESF. This requirement can be disabled for LIST commands using the allow-list configuration option.
  2. The MLDAP ESM Module checks to see if the user has execute permission for a resource with the same name as the command (for example ADDUSER) under the class AdminAPI. See the complete list of esfadmin sub-commands in the section esfadmin Sub-commands. This class is optional, and if there is no applicable rule, access is allowed.
  • 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

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 LDAP Security Manager from the Enterprise Server UI


Changing User Passwords Stored in an LDAP

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 (for example from the CICS signon screen).

  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 LDAP Security Manager from the Enterprise Server UI


About Users, Groups and Resources

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.

MSS resources use various class names defined by IBM. Non-MSS resources, such as ES configuration definitions in MF Directory Server, use resource class names defined by Micro Focus (using syntax that's not permitted for MSS resource class names, to avoid collisions). 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.

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 LDAP Security Manager 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

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 LDAP Security Manager from the Enterprise Server UI


To Add a User

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, 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

  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

  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

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

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 LDAP Security Manager from the Enterprise Server UI


To Add a Group

  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

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

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

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

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 LDAP Security Manager from the Enterprise Server UI


About Resource Security

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

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

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

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

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

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

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

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

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

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


ESF LDAP Security Administration Web Interface

You can use the ESF LDAP security administration Web interface to configure LDAP for use with your Enterprise Server installation. This alternative browser-based interface enables you to administer the LDAP information outside of the MFDS user interface. It enables you to display and administer large numbers of users, groups and resources.

Note: The user used to login to the Web interface requires Update, Add, Delete access from the User Administration resource. This resource can be found under the Enterprise Server Administration resource class in LDAP.

Features

The ESF LDAP security administration Web interface has the following features:

  • Browser based graphical display of the users, groups, resource classes, and resource entities that are defined in a configured LDAP-compatible security manager such as Microsoft Active Directory, AD LDS or OpenLDAP.
  • Ability to easily sort and filter users, groups, classes, and resources.
  • Enhanced experience independent of the MFDS user interface enabling segregation of the LDAP security manager administration role from the Enterprise Server configuration and operational role.
  • Takes advantage of the new ESF LISTREFERENCES feature to enable easy determination of relationships among security objects and rules.

Limitations

The ESF LDAP security administration Web interface has the following limitations:

  • Support for nested groups is not provided within the interface. If required, you can administer nested groups from the esfadmin command-line utility.
  • Actions taken in the interface are applied to all the security managers in the security manager list. Therefore, Micro Focus recommends you only have one security manager in the security manager list. You can administer multiple different security managers by defining separate Enterprise Server regions to host the ESF LDAP security administration Web interface for each security manager required.
  • Prerequisites
  • Configuring the ESF LDAP Security Administration Web Interface
  • Operation
  • ESF LDAP Properties
Parent topic: Securing an Enterprise Server Installation


Prerequisites

The ESF LDAP administration Web interface has the following software requirements:

  • A Web browser (with a minimum required version):
    • Internet Explorer (version 11.0)
    • Firefox (version 39.0)
    • Chrome (version 43.0)
  • A listener configured as described in Configuring the ESF LDAP Security Administration Web Interface.
Parent topic: ESF LDAP Security Administration Web Interface
Related reference
Configuring the ESF LDAP Security Administration Web Interface


Configuring the ESF LDAP Security Administration Web Interface

The following steps provide guidance on how to enable the ESF LDAP security administration Web interface for a typical security manager configuration. See Configure ES Security for more information on configuring a security manager. Amend some of these steps as required for your particular configuration.

Although a listener is required to access the new ESF LDAP security Web interface, it is not necessary to manually create a listener as one is created automatically by performing the following steps:

  1. Navigate to the Enterprise Server Administration home page by clicking Home on the left pane.
  2. Click Edit on the row corresponding to the server that you want to use to access the Web interface.
    Note: Ensure that the server you create the listener for is stopped.
  3. Click Server > Properties > Security.
  4. Uncheck Use default ES Security Manager configuration.
  5. Click Apply.
  6. You need to check Use all groups in Security Facility Configuration if the user you intend to login with is not in the User Administration resource. For example, if you are using the default SYSAD user.
    Note: You need a user that has administration privileges, checking Use all groups ensures that the user has the permissions of all the groups they currently belong to, including the #DSAdmin group which provides access to user administration. If you have created a custom user with administration privileges associated with their default group you can use this without the need to check Use all groups.
  7. Click Apply.
  8. In the Security Managers List, click Add.

    This opens the Security Managers List page.

  9. Click Select for the row that contains the security manager that you want to associate with this server.
  10. Click Add.

    This adds the security manager to the server's Security Manager List. This server is then accessible with the new Web interface.

  11. Type the port number that you want the ESF LDAP security administrator Web interface to be accessed on, in the Use port field.

    If you use 0 as the port number then a dynamic port number will be allocated when the server is restarted.

  12. Check Enable Security Manager Administration GUI, and then click Apply.

    You can verify that the listener has been added by looking for an ESF Administration GUI entry in the listeners tab

  13. Click Server > Control, and then click Start.
  14. Use credentials appropriate to your security manager, and then click OK to continue.

    This reopens the Enterprise Server Administration home page.

  15. You must wait till the server has started, and then click Edit on the server you have been configuring.
  16. Click Server > Properties > Security.
  17. Click the URI provided just below the Enable Security Manager Administration GUI checkbox.

    This opens the ESF LDAP security administration Web interface within a browser. Alternatively, you can type the URI into one of the supported browsers listed in Prerequisites. You are prompted to type in your username and password before the interface opens.

    Note: If the security administration Web interface does not open after the username and password are entered, check the communications log (log.html) for errors. Certain browsers may cache information and it may be necessary to clear the cache and/or restart the browser in order to enter correct or different security credentials.
Parent topic: ESF LDAP Security Administration Web Interface
Related concepts
Prerequisites
Related reference
MLDAP ESM Module Custom Configuration Information
Configuring mldap_esm Security Manager for an LDAP
Configure ES Security


Operation

You can access the ESF LDAP security administration Web interface using the URI provided on the Server > Properties > Security tab, under the Enable Security Manager Administration GUI checkbox. Depending on the how you have configured the security manager, you might be prompted for an administrator's username and password.

The interface has a number of tabs, where each tab has a number of columns presenting various information. You can:

  • Filter the rows by typing a string in the Search field and pressing Enter.

    The number of entries is displayed right next to the Search field.

  • Change the order of the columns - drag a column to a new position.
  • Perform an action on a column - click [image] on the column header to see a list of the available actions:

    Every tab has an Action column. Click [image] to view a list of the actions that can be performed on the item in the selected row.

  • Sort the columns in ascending or descending order.
  • Hide columns by unchecking the column name.
Note: Refreshing the page or reopening the browser resets the columns displayed and their order to the default configuration.

Users tab

By default, the User tab displays the Action, Order, Account Id, Name and Description columns. You can search in this tab which filters the users and only displays the users that contain the string in the Account Id or Name columns.

Group tab

By default, the Group tab displays the Action, Order, Group and Description columns. You can search in this tab which filters the groups and only displays the groups that contained the string in the Group or Description columns.

Resources tab

By default, the Resources tab displays the Action, Classes / Resources, Description and ACL String columns. The Classes / Resources column provides a tree view of the resource classes and associated resource entities. Click [image] to expand the resource class and view any associate resource entities. You can search in this tab which filters the class resources and only displays the class resources that contain the string in the Classes / Resources or Description columns.
Note: Searching in this tab only filters the resource classes and does not return any matching resource entities.

Configuration tab

By default, the Configuration tab displays the Action, Order, Name and Module columns. This tab lists the security manager configurations of the Enterprise Server region in use.

Click [image] to display the Advanced Configuration Information dialog box and view the information used to configure the security manager such as:

  • Name
  • Module
  • Connection Path
  • Authorized ID
  • Enabled
  • Cache Limit (KB)
  • Cache TTL
  • Configuration Information
Note: This tab does not include a Search field or a count of the entries.
  • Managing Users
    Adding, editing and deleting a user.
  • Managing Groups
    Adding, editing, deleting and viewing group permissions.
  • Managing Resource
    Adding, editing and deleting resource classes and resource entities.
Parent topic: ESF LDAP Security Administration Web Interface
Related reference
Users
Groups
Resource Classes
Resource Entities


Managing Users

Adding, editing and deleting a user.
Note: In order to manage users, your user's account must have administrator's permissions.
  • To Add a User
  • To Edit a User
  • To Delete a User
Parent topic: Operation


To Add a User

To add a user perform the following steps:

  1. On the User tab, click Add User.

    This opens the Add a User dialog box.

  2. Specify the user's details.

    For further information about the fields refer to the User section.

  3. Click OK.
Parent topic: Managing Users
Related reference
Users


To Edit a User

To edit a user perform the following steps:

  1. On the User tab, click [image] in the row containing the user you want to edit, then click Edit User.

    This opens the User Config dialog box.

  2. Edit the fields as required.

    For further information about the fields refer to the User section.

  3. Click OK.
Parent topic: Managing Users
Related reference
Users


To Delete a User

To delete a user perform the following steps:

  1. On the Users tab, click [image] in the row containing the user you want to delete, then click Delete User.

    This opens the Confirm dialog box. This prompts you to confirm the action to delete the user.

  2. Click Yes.
Parent topic: Managing Users


Managing Groups

Adding, editing, deleting and viewing group permissions.
Note: In order to manage the group, your user's account must have administrator's permissions.
  • To Add a Group
  • To Edit a Group
  • To Delete a Group
Parent topic: Operation


To Add a Group

To add a group perform the following steps:

  1. On the Group tab, click Add Group.

    This opens the Add a Group dialog box.

  2. Type the group name in the Name field.
  3. Type the group description in the Description field.
  4. Click OK.
Parent topic: Managing Groups
Related reference
Groups


To Edit a Group

To edit a group perform the following steps:

  1. On the Group tab, click [image] in the row containing the group you want to edit, then click Edit Group.

    This opens the Group Config dialog box.

  2. Specify the details for the group.

    For further information about the fields refer to the Groups section.

  3. Click OK.
Parent topic: Managing Groups
Related reference
Groups


To Delete a Group

To delete a group perform the following steps

  1. On the Group tab, click [image] in the row containing the group you want to delete, then click Delete Group.

    This opens the Confirm dialog box.

  2. Click Yes.
Parent topic: Managing Groups


Managing Resource

Adding, editing and deleting resource classes and resource entities.
Note: In order to manage resources, your user's account must have administrator's permissions.
  • To Add a Resource Class
  • To Add a Resource Entity
  • To Edit a Resource Class
  • To Edit a Resource Entity
  • To Delete a Resource Class
  • To Delete a Resource Entity
Parent topic: Operation


To Add a Resource Class

To add a resource class perform the following steps:

  1. On the Resources tab, click Add Class.

    This opens the Add a Class dialog box.

  2. Specify the Class details

    For further information about the fields refer to the Resource Class section.

  3. Click OK.
Parent topic: Managing Resource
Related reference
Resource Classes


To Add a Resource Entity

Resource entities can only be added to resource classes. To add a resource entity perform the following steps:

  1. On the Resources tab, click [image] in the row containing the class resource you want to edit, then click Edit Class.

    This opens the Class Config dialog box.

  2. Click Resources tab.
  3. Click Add a Resource.

    This opens the Add a Resource dialog box. For further information about the fields refer to the Resource Entity section.

  4. Click OK.

    The resource entity is added to the list in the Class Config dialog box.

  5. Click OK.
Parent topic: Managing Resource
Related reference
Resource Entities


To Edit a Resource Class

To edit a resource class perform the following steps:

  1. On the Resources tab, click [image] in the row containing the resource class you want to edit, then click Edit Class.

    This opens the Class Config dialog box.

  2. Specify the details for the resource class.

    For information about the fields, please refer to the Resource Class section.

  3. Click OK.
Parent topic: Managing Resource
Related reference
Resource Classes


To Edit a Resource Entity

To edit a resource entity perform the following steps:

  1. On the Resources tab, expand the tree view for the class that contains the resource entity that you want to edit. You can expand the tree nodes by clicking on the [image] icon.
  2. Click [image] in the row containing the resource entity you want to edit, then click Edit Resource.
  3. Specify the details for the resource entity in the Resource Config dialog box.

    For information about the fields, please refer to the Resource Entity section.

  4. Click OK.
Parent topic: Managing Resource
Related reference
Resource Entities


To Delete a Resource Class

To delete a resource class perform the following steps:

  1. On the Resources tab, click [image] in the row containing the resource class you want to delete, then click Delete Class.

    This opens the Confirm dialog box.

  2. Click Yes to confirm the permanent deletion of the resource class.
    Note: You can not delete a resource class if it has attached resource entities. You must delete all attached resource entities before you can delete the parent resource class.
Parent topic: Managing Resource


To Delete a Resource Entity

To delete a resource entity perform the following steps:

  1. On the Resources tab, expand the tree view for the class that contains the resource entity that you want to delete. You can expand the tree nodes by clicking on the [image] icon.
  2. Click [image] in the row containing the resource entity you want to edit, then click Delete Resource.

    This opens the Confirm dialog box.

  3. Click Yes to confirm the permanent deletion of the resource entity.
Parent topic: Managing Resource


ESF LDAP Properties

You can configure the ESF LDAP properties from the various tabs by clicking on the action icon and specifying the following:

  • Users
    You can specify properties about your ESF LDAP users on the User Config dialog box.
  • Groups
    You can specify properties about your ESF LDAP groups on the Group Config dialog box.
  • Resource Classes
    You can specify properties about your ESF LDAP resource classes on the Class Config dialog box.
  • Resource Entities
    You can specify properties about your ESF LDAP resource entities on the Resource Config dialog box.
Parent topic: ESF LDAP Security Administration Web Interface


Users

You can specify properties about your ESF LDAP users on the User Config dialog box.

Properties

List of properties and their definitions.

Account ID
The ID for the user account.
Name
The full name of the person assigned to this account.
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
Indicates whether this user can logon.
Must Change Password
Forces the user to specify a new password the first time they login.
Description
A description of the user account.
Password
Specifies the new password of the user. Password lengths are restricted to 8 or fewer characters if you are logging into an MSS such as CICS, JES or IMS. The password length is limited to 20 or fewer characters if you are logging into MFDS. If you leave this field blank, the existing password is unchanged.
Note: Multibyte characters, whitespace, some punctuation characters, and control characters may cause problems in passwords. Some external security managers restrict which characters can be used in passwords, and some characters may be altered by ASCII-EBCDIC translation if passwords are entered through 3270 terminal sessions. Micro Focus recommends using letters, numbers, and punctuation characters that are in both ASCII and the default EBCDIC code page.
Confirm Password
Specify the case-sensitive new password of the user. If you enter a value that does not match the value in Password, an error is generated and the existing password is unchanged.

Advanced

Advanced properties and their definitions.

UID
Specifies the Unique reference ID, if this is not supplied then one is generated automatically when the user is created.
Operator ID
Specifies the 3-byte MSS operator ID associated with the unique reference ID.
Timeout (mins)
Specifies the MSS user timeout in minutes.
Password Expires
Specifies the 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. To simplify the selection of an expiry date, click [image] to display a calendar.
Use Token
Permission to use passtokens.
Create Token
Permission to create passtokens
Custom Configuration
Custom text (not used by Micro Focus).

Group Membership

List of groups that the user has joined on the left side and a list of all available groups on the right side.

Joined
This is a list of all the groups that the user has joined.
Groups
This is a list of all the groups that are available to join.

References

Lists the references associated with the user. This includes a reference to the user itself and the default group if defined in the Properties tab.

Type
Displays the object type and can be USER, GROUP or RESOURCE.
Name
Name of the references.
Comment
Provides information on the type of reference and can be one of the following:
  • The user itself
  • User's default group
  • Explicit group member
Parent topic: ESF LDAP Properties
Related concepts
Operation
To Add a User
To Edit a User


Groups

You can specify properties about your ESF LDAP groups on the Group Config dialog box.

Properties

List of properties and their definitions:

Description
A description of the group.

Members

Users member properties and their definitions:

Members
This is a list of all the users that are members of the group.
Users
This is a list of all the users that are available to join the group.

References

Lists the references associated with the user. This includes a reference to the group itself as a default:

Type
Displays the object type and can be USER, GROUP or RESOURCE.
Name
Name of the reference.
Comment
Provides information on the type of reference and can be one of the following:
  • The group itself
  • Explicit group member
Parent topic: ESF LDAP Properties
Related concepts
Operation
To Add a Group
To Edit a Group


Resource Classes

You can specify properties about your ESF LDAP resource classes on the Class Config dialog box.
Name

Specify the unique name of the resource class.

Description

Specify a description of the resource class.

Parent topic: ESF LDAP Properties
Related concepts
Operation
To Add a Resource Class
To Edit a Resource Class


Resource Entities

You can specify properties about your ESF LDAP resource entities on the Resource Config dialog box.
Name

Specify the unique name of the resource class.

Description

Specify a description of the resource class.

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: ESF LDAP Properties
Related concepts
Operation
To Add a Resource Entity
To Edit a Resource Entity


Migrating from Enterprise Server Early Versions

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
  • AD LDS Migration Tasks
  • Importing Existing ES/MSS Users into Active Directory
Parent topic: Securing an Enterprise Server Installation


Integrating Security from Early Releases: casesm

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

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

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

  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

  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


AD LDS Migration Tasks

This section details the tasks required to migrate your security configuration used by Enterprise Server configured using the previous Enterprise Server security infrastructure, that is up to and including release 5.1 Websync 2..

  • To extend an AD LDS repository to support Enterprise Server configuration objects
  • To update an extended AD LDS repository to support changes to Enterprise Server configuration objects
  • To migrate Directory Server users to an AD LDS repository
  • To Migrate Enterprise Server Users to an AD LDS Repository
  • To configure the security facility to use the MLDAP ESM
  • Implementing Enterprise Server Security with Active Directory
Parent topic: Migrating from Enterprise Server Early Versions


To extend an AD LDS repository to support Enterprise Server configuration objects

  1. Create an LDIF file containing the required schema extensions by using the mfds -L command. For example, at the command line, enter:
    mfds -L DC=X 1 mfds_schema.ldf

    This creates an LDIF file mfds_schema.ldf. The DC=X specifies distinguished name for the schema partition string assigned to each entry in the LDIF file. You could specify the actual destination here, but typically you will want to create a portable file. In this example, we use DC=X and replace it with the appropriate value when we import.

  2. Use the LDIFDE command to import the generated LDF file into AD LDS. For example,
    ldifde -I -v -k -c "DC=X" CN=Schema,CN=Configuration,
DC=customer_dom,DC=com -f mfds_schema.ldf

    The -c option replaces the schema partition string specified when creating the LDIF file with the schema partition into which the objects are to be imported. In this example, the container is CN=Schema,CN=Configuration, DC=customer_dom,DC=com but it will vary depending on your particular circumstances. If using AD LDS, the schema partition root can be extracted using the schemaNamingContext RootDSE attribute value e.g.

    ldifde -i -f mfds-schema.ldf -s -k -v -j . -c "DC=X" #schemaNamingContext
Important: You must have sufficient rights to modify the LDAP schema and the schema must be writable.
Parent topic: AD LDS Migration Tasks


To update an extended AD LDS repository to support changes to Enterprise Server configuration objects

If you have previously extended an AD LDS repository to support Enterprise Server configuration objects, you will need to update the schema to include later changes. The steps involved are described below. If you have not previously extended the repository, simply follow the instructions in

  1. Create a delta LDIF file file containing the latest schema extensions by using the mfds -L command. For example, at the command line, enter:
    mfds -l DC=X 1 AD_MF_schema_delta.ldf 0 1

    This creates an LDIF file mfds_schema.ldf. The DC=X specifies distinguished name for the schema partition string assigned to each entry in the LDIF file. You could specify the actual destination here, but typically you will want to create a portable file. In this example, we use DC=X and replace it with the appropriate value when we import.

    The 1 following DC=X indicates that the generated file is to be in Active Directory/AD LDS format. The 0 following the file name indicates that a delta containing the most recent definitions should be generated. The 1 at the end of the command indicates that the delta is to include definitions since version 1 of the schema (version 1 was released with Net Express WS02).

  2. Use the LDIFDE command to import the generated LDF file into AD LDS. For example,
    ldifde -i -v -k -c "DC=X" CN=Schema,CN=Configuration,
DC=customer_dom,DC=com -f mfds_deleta.ldf

    The -c option replaces the schema partition string specified when creating the LDIF file with the schema partition into which the objects are to be imported. In this example, the container is CN=Schema,CN=Configuration, DC=customer_dom,DC=com but it will vary depending on your particular circumstances. If using AD LDS, the schema partition root can be extracted using the schemaNamingContext RootDSE attribute value e.g.

    ldifde -i -f mfds-delta.ldf -s -k -v -j . -c "DC=X" #schemaNamingContext
Important: You must have sufficient rights to modify the LDAP schema and the schema must be writable.
Parent topic: AD LDS Migration Tasks


To migrate Directory Server users to an AD LDS repository

Before you can do this, the target repository must be extended 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 create 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.

  1. Create an LDIF file file containing the user and group definitions by using the mfds -e command. For example, at the command line, enter:
    mfds -e "CN=Micro Focus,CN=Program Data,DC=local" "CN=Enterprise Server Users"
"CN=Enterprise Server Groups" "CN=Enterprise Server Resources" 1 mfds_users.ldf
    In this example:
    "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

    This creates an LDIF file mfds_users.ldf.

  2. Use the LDIFDE command to import the generated LDF file into AD LDS. For example,
    ldifde -i -f fds_users.ldf -s localhost:389 -k -v -j
Important: You must have sufficient rights to modify the AD LDS container and the container must be writable.
Parent topic: AD LDS Migration Tasks


To Migrate Enterprise Server Users to an AD LDS Repository

Before you can migrate your users, the target repository must be extended 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 create 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.

The Monitor and Control users are defined in Sign On Table (SNT) entries. These are stored in a file called dfhdrdat. By default this is stored in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\cas . This has an associated index file, dfhdrdat.idx. Both files must be in the same location. If dfhdrdat.idx doesn't exist, it is created the first time dfhdrdat is accessed.

  1. Use the cas-to-ad.exe utility to do migrate the users. The utility has a number of options for specifying your LDAP directory credentials, target container, server details, path to the dfhdrdat file, password encoding and the information to be displayed.

    Examples:

    cas-to-ad
    cas-to-ad -u myuser -p password -r . -l localhost:389

    This extracts user definitions from dfhdrdat and attempt to import them into your LDAP Directory.

Parent topic: AD LDS Migration Tasks


To configure the security facility to use the MLDAP ESM

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.
Parent topic: AD LDS Migration Tasks
Related concepts
Configuring Microsoft Users
Related tasks
To Configure a Security Manager's Environment


Implementing Enterprise Server Security with Active Directory

If you enable external security in Enterprise Server, then you need to understand the implications and how security is checked upon an action. This document describes the relationship between a user and the different classes used to implement security.

In order to use External Security with Enterprise Server, you need first to create users and groups in Active Directory. These users and groups will have different properties, these properties will be used to verify that the user can access a resource.

Parent topic: AD LDS Migration Tasks


Importing Existing ES/MSS Users into Active Directory

You can import existing ES/MSS users from a CAS RDO (Resource Definition Online) file into Active Directory.

To import those users, use the Micro Focus cas-to-ad utility. This program reads a CAS RDO file, adding each user it finds to AD. (It will also try to add the CAS system users such as CICSUSER, but they were already added in the previous step.) The basic command is:

cas-to-ad -u - -d "domain-DN" -c "user-container" -l servername -U userclass

Be sure to enter the options just as shown above - they are case-sensitive. Ignore any warning messages about users that already exist.

The user-container parameter will typically be either "CN=Enterprise Server Users,CN=Micro Focus,CN=Program Data" if you are using microfocus-MFDS-User, or "CN=Users" if you are using Windows users (the Microsoft user class).

The servername parameter can also be specified as a URL, as in "-l ldap://servername". If your LDAP server uses a non-default port, you can specify that as well.

You can also use LDAP-over-SSL by using an "ldaps" URL: "ldaps://servername". (Requires cas-to-ad 1.4.0 or later.) This will only work if your server supports LDAP-over-SSL (this is usually true with Active Directory running on newer Windows domain controllers). Also, the LDAP client library will have to verify the Active Directory server's certificate, which may fail if your server uses a certificate signed by an unusual Certification Authority. If you want to use LDAP-over-SSL but cas-to-ad fails to connect to AD, contact your AD administrator for a copy of the signing certificate and instructions for installing it in your client system's trusted root certificate store.

cas-to-ad will look for the RDO file (dfhdrdat) in the directory specified by the environment variable TXRDTP. If that environment variable is not set, cas-to-ad looks in the current directory, then in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\cas directory (default location). To specify a different location, add "-r path" to the command line.

If cas-to-ad complains that it can't open your RDO file, it may be in use. Copy dfhdrdat.* to a temporary directory and use the -r path option to tell cas-to-ad to use the copy.

The "-u -" option binds (logs on) to AD as the current Windows user. If you are not logged in as a user with the necessary authority, or if you are running cas-to-ad remotely from a system in a different domain, you will need to specify a different user ID. You will also be prompted for a password, unless you specify it on the command line with the -p option. For example:

cas-to-ad -u domain\Administrator

or

cas-to-ad -u "CN=Administrator,CN=Users,domain-DN"

or to avoid having to enter the password when prompted:

cas-to-ad -u domain\Administrator -p password

Run "cas-to-ad -h" for a usage message to see other options.

Note that in some cases AD may not let you set passwords on unencrypted connections, so this command may fail if you use the -u option. This should be fixed in a future release; for now, if you encounter this problem, run cas-to-ad on a system in the same domain as the AD server. You can also get an encrypted connection by using LDAP-over-SSL, as described above.

  • Create MFDS objects LDIF file
  • Set MFDS user passwords
  • Import the MFDS Objects
Parent topic: Migrating from Enterprise Server Early Versions


Create MFDS objects LDIF file

Extract MFDS users, groups, and resources from your existing MFDS configuration:

mfds -e "domain-DN" "user-container" "CN=Enterprise Server User Groups,CN=Micro Focus,CN=Program Data" "CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data" 1 mfds_users.ldf userclass

Set domain-DN, user-container, and userclass as in previous commands. Be careful not to confuse user-container (CN=...) and userclass (microfocus-MFDS-User or user), which is easy to do.

(If you are using AD LDS rather than AD, you can specify "0" instead of "1" before mfds_users.ldf. This will produce a slightly different .ldf file that will tell AD LDS that the passwords for the MFDS users do not expire.)

This command will create mfds_users.ldf.

Parent topic: Importing Existing ES/MSS Users into Active Directory


Set MFDS user passwords

If you are using the microfocus-MFDS-User object class for your users, MFDS will set their password attribute (microfocus-MFDS-User-Pwd) in mfds_users.ldf using the password hashes it has for those users. This means MFDS users will continue to have the same passwords.

If you are using the user object class for your users, currently MFDS does not set user password attributes, which means the newly-imported MFDS users have no passwords. Until this is fixed, you will either need to edit the mfds_users.ldf file before importing it and add the appropriate password attributes, or you will have to set the passwords manually after the users are imported:

  • To set a password in the LDIF file, add this attribute to the user: userPassword: password (AD will automatically encrypt this password.)
  • To set a password manually, you can use the Microsoft ADSI Edit utility ADSIedit.msc: right-click on a user and choose "Reset Password".
  • You can also use normal Windows system administration mechanisms to set user passwords, since the user class uses standard Windows passwords.

At a minimum, you will need at least one MFDS administrative user with a password (such as schemaadmin), so you can log on to MFDS. Typically, you will also want at least one user with "modify" authority for use by ES and MFCS; this will usually be an MSS user as well, since it will need MSS authority to start and stop the region (if security is configured for the ES server). The SYSAD user is usually used for this purpose, at least during initial installation and verification. (You can delete these users later.)

If you want to continue using unsecured ES regions, you will need to set the passwords for the mf_cs and mf_mdsa predefined users.

By default, the passwords for MFDS predefined users are the same as their usernames.

Once you have successfully configured ES LDAP-based security for MFDS, you may also be able to use MFDS to set passwords, depending on details of your configuration.

Parent topic: Importing Existing ES/MSS Users into Active Directory


Import the MFDS Objects

ldifde -i -f mfds_users.ldf -s servername -k -j .

Note that since you specified your domain-DN when creating mfds_users.ldf, you do not need a -c option for this command.

Parent topic: Importing Existing ES/MSS Users into Active Directory


Security Reference Information

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

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
  • Variables for Configuring MSS Security Behavior
  • Environment Variables for CICS Resource Classes
Parent topic: Security Reference Information
Related concepts
User Impersonation for CICS and JCL


Enterprise Server Default Users and Associated Environment Variables

Enterprise Server has a set of default users that are used when no user is logged on for CICS, JES, IMS or ESMAC authentication. These users and the associated environment variables are:
Environment | User | Associated Environment Variable
ESMAC | mfuser | ES_USR_DFLT_ESMAC
CICS | CICSUSER | ES_USR_DFLT_CICS
JES | JESUSER | ES_USR_DFLT_JES
IMS | IMSUSER | ES_USR_DFLT_IMS

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


Variables for Configuring MSS Security Behavior

The variables below are used to control CICS and IMS security processing. They correspond to CICS and IMS intialization parameters for the mainframe, with a prefix of ES_ESM.

  • ES_ESM_CMDSEC
  • ES_ESM_IDPW_CASE
  • ES_ESM_PLTPISEC
  • ES_CESN_NO_OS390
  • ES_ESM_PLTPIUSR
  • ES_ESM_RCF
  • ES_ESM_RESSEC
  • ES_ESM_SECPRFX
  • ES_ESM_XUSER
  • ES_OLD_SEC_TSTD
  • ES_SURROGATE_JOB_USER
Parent topic: Environment Variables used in Enterprise Server Security


ES_ESM_CMDSEC

Use this variable to determine whether CICS processing should honor the CMDSEC option specified on a transaction's PLT definition.
Setting | Result
ASIS | The CMDSEC option of a transaction's resource definition will be honored. That is, command security checking is performed only when CMDSEC is set to YES on the transaction resource definition.
ALWAYS | CICS processing always performs command security checking irrespective of the CMDSEC setting on the transaction definition.
Parent topic: Variables for Configuring MSS Security Behavior


ES_ESM_IDPW_CASE

Use this variable if you have the following specific situations:
  1. An installation with an ESM that does not have case sensitive user IDs (for example: when sysad, SYSAD, SysAd and other case combinations are all recognized by the ESM as the same user).
  2. An installation where all user IDs are of the same case: either uppercase or lowercase.
  3. An installation where the user IDs are of mixed case, and you would like to suppress any additional ESM authorization attempts for keying errors.
  4. Only ESM-backed security is affected.

You use the environment variable with a format ES_ESM_IDPW_CASE=xy, where "x" is the folding option for user ID, and "y" the option for password. The settings for "x" and "y" are:

Setting | Result
U | Always uppercase
L | Always lowercase
M | Mixed case and case sensitive

When this environment variable is set, Enterprise Server will make only one attempt to identify a user, presenting the user ID and password as-is (M), folded to uppercase (U) or folded to lowercase(L). If this environment variable is not set, the legacy Enterprise Server behavior will be used.

For CICS legacy behavior, the user ID and password are used as given, and subject to any uppercase translation configuration of the sign-on transaction or terminal characteristics.

For ESMAC and IMS legacy behavior, there is potentially more than one authentication attempt. First, the user ID and password are used as given. If the authentication fails, the user ID is folded to uppercase and the authentication re-tried. If this fails as well, both the user ID and the password are folded to uppercase and the authentication re-tried.

ES_ESM_IDPW_CASE=UM - a single authentication is tried with the user ID folded to uppercase, and the password used as-is.
Parent topic: Variables for Configuring MSS Security Behavior


ES_ESM_PLTPISEC

Use this variable to choose the desired level of security checking for PLTPI processing.
Setting | Result
NONE | No security will be performed for PLTPI processing. This is the default level of security checking.
ALL | Resource security check and Command security check will be performed
RESSEC | Only Resource security check will be performed
CMDSEC | Only Command security check will be performed
Parent topic: Variables for Configuring MSS Security Behavior


ES_CESN_NO_OS390

Use this variable to override the default behaviour CESN transaction response for invalid user credentials. Default behaviour reports "Your userid is invalid" or "Your password is invalid". Setting this variable to any value will cause CESN to produce an invalid credential message instead.

Example:

ES_CESN_NO_OS390=secured
Parent topic: Variables for Configuring MSS Security Behavior


ES_ESM_PLTPIUSR

Use this to specify the userid under the authority of which PLT programs will run during CICS initialization. The userid must have appropriate authorization (as determined by the PLTPISEC parameter) to access all the resources used by the programs. Enterprise Server will check that the CICS region has authority to act as a surrogate for the userid specified.

If you do not specify PLTPIUSR, the user specified when starting the enterprise server/CICS region is used. Where this is the case, this user must have appropriate authorization on the resources used by the PLT programs.

Parent topic: Variables for Configuring MSS Security Behavior


ES_ESM_RCF

Use this variable if RACF is to be used for command authorization.
Setting | Result
A | Includes options T, C, and S.
C | Specifies that RACF is to be used for ETO terminal command authorization.
N | Specifies that no sign-on, transaction, or command authorization is to be performed by RACF.
S | Specifies that RACF is to be used for static and ETO terminal command authorization. Includes option C.
T | Specifies that RACF is to be used for sign-on and transaction authorization.
Y | Includes options T and C.
Parent topic: Variables for Configuring MSS Security Behavior


ES_ESM_RESSEC

Use this parameter to determine whether CICS processing should honor the RLS security setting specified on a transaction definition (PCT).
Setting | Result
ASIS | The RLS security setting of a transaction will be honored. That is, resource level security checking is performed only when the RLS security checkbox is marked in the PCT definition.
ALWAYS | CICS processing always performs resource level security checking irrespective of the RLS security setting on the transaction definition.
Parent topic: Variables for Configuring MSS Security Behavior


ES_ESM_SECPRFX

Use this to determine whether or not CICS processing should prefix the resource names when making security queries.
Setting | Result
NO | No prefixes are used
YES | Resource names are prefixed with the CICS region user ID.
prefix | This string will be used as the prefix for resource names. It can be 1 to 8 upper case alphanumeric characters and it must start with an alphabetic character.
Parent topic: Variables for Configuring MSS Security Behavior


ES_ESM_XUSER

Use this to determine whether or not CICS processing will perform surrogate user checks.
Setting | Result
NO | No surrogate user checking is performed.
YES | Perform surrogate user checking wherever such checks are permitted.
Parent topic: Variables for Configuring MSS Security Behavior


ES_OLD_SEC_TSTD

Use this to prevent security being enforced for TS or TD queues that are not defined in your security repository.
Setting | Result
Any value | Security will not be enforced for TS and TD queues that are not defined as entities within the security repository.
Important: If you do not set this variable, and you enable security for your enterprise server, you must declare each TS or TD that your transactions will access in your security repository.
Parent topic: Variables for Configuring MSS Security Behavior


ES_SURROGATE_JOB_USER

Use this to associate a user ID with a job when submitting for processing through the internal reader from CICS.
Setting | Result
Any value | The user ID that started the ES region is used in the job submission.
No value | The CICS default user CICSUSER, or as specified by ES_USR_DFLT_CICS, is used in the job submission.
Parent topic: Variables for Configuring MSS Security Behavior


Environment Variables for CICS Resource Classes

The variables listed below can be used to override the default CICS resource classes.

Environment variable | Default class | Possible values | Prefix letter if a name is specified + 7 letters of the name
ES_CLASS_XPCT | ACICSPCT | YES/NO/NAME | A
ES_CLASS_XCMD | CCICSCMD | YES/NO/NAME | C
ES_CLASS_XDCT | DCICSDCT | YES/NO/NAME | D
ES_CLASS_XFCT | FCICSFCT | YES/NO/NAME | F
ES_CLASS_XJCT | JCICSJCT | YES/NO/NAME | J
ES_CLASS_XPPT | MCICSPPT | YES/NO/NAME | M
ES_CLASS_XPSB | PCICSPSB | YES/NO/NAME | P
ES_CLASS_XRES | RCICSRES | YES/NO/NAME | R
ES_CLASS_XTST | SCICSTST | YES/NO/NAME | S
ES_CLASS_XTRAN | TCICSTRN | YES/NO/NAME | T

For instance if you set ES_CLASS_XTRAN to the value MYTRANS then CICS will look for TMYTRANS as the class.

Parent topic: Environment Variables used in Enterprise Server Security


Resource Classes used by Enterprise Server

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.

MSS resources use various class names defined by IBM. Non-MSS resources, such as ES configuration definitions in MFDirectory Server, use resource class names defined by Micro Focus (using syntax that's not permitted for MSS resource class names, to avoid collisions). 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.

When Enterprise Server executes application programs in the various MSS processing regimes, it makes the appropriate security queries. This behaviour is intended to emulate, as far as is feasible, that found on IBM mainframe platforms. The entities and classes used are specified in the tables listed below.

  • Resource Classes for CICS Security
  • Resource Classes for ESF Features
  • Resource Classes for JES Security
  • Resource Classes for IMS Security
  • 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.
  • Resource Classes for WebSphere MQ
  • CICS Resource and Command Checks
Parent topic: Security Reference Information


Resource Classes for CICS Security

The table below defines the name of each default resource class used in Enterprise Server for CICS security, its meaning, the type of resource entities it contains, and the minimum permission that a user requires on the entities.

Note:

The CICS class names can be configured using environment variables (see Environment Variables for CICS Resource Classes). CICS will only use the first 7 characters of the value specified in the environment variable, it will then prefix the value with 1 character depending on the request.

CICS Class name | CICS corresponding | Entities | ACCESS LEVEL
ACICSPCT | CICS Program control table | Started Transactions | READ
CCICSCMD | Used by CICS/ESA 3.1, or later, to verify that a user is permitted to use CICS system programmer commands such as INQUIRE, SET, PERFORM, and COLLECT | CICS Command Functions | See resource and cross reference table
DATASET | Dataset Names or Physical Filename used by CICS at startup | Files | READ or UPDATE
DCICSDCT | CICS Transient data queues | Transient Data Destination | UPDATE
FCICSFCT | CICS File control table | Files | READ or UPDATE
JCICSJCT | CICS Journal control table | Journal Number | READ or UPDATE
MCICSPPT | CICS Processing program table (LINK/XCTL) | Programs | READ
PCICSPSB | CICS Program specification blocks (PSBs) | Program Status Block | N/A
SCICSTST | CICS temporary storage queues | Temporary Storage Queues | READ or UPDATE
TCICSTRN | CICS Transactions | Transactions | READ
SURROGAT | Class for CICS SURROGATE users (EXEC CICS START USERID). | Users | READ
Note:

In previous releases, security was not enforced for TS or TD queues that were not declared in the security repository. Now, by default, you must declare each TS or TD that your transactions will access. To revert to the previous behaviour, use the ES_OLD_SEC_TSTD environment variable.

Parent topic: Resource Classes used by Enterprise Server


Resource Classes for ESF Features

AdminAPI

This optional class can be used to restrict access to the ESF Administration facility. Resources are named for ESF Admin commands, for example ADDUSER and ALTGROUP. If an applicable rule is defined in this category, the user making the Admin request must have execute permission or the request is denied.

Parent topic: Resource Classes used by Enterprise Server


Resource Classes for JES Security

The table below defines the name of each default resource class used in Enterprise Server for JES security, its meaning, the type of resource entities it contains, and the minimum permission that a user requires on the entities.

DATASET
JES relation | Entities | ACCESS LEVEL
Dataset Names | Files | None, Read, Update, Alter
JESINPUT
JES relation Entities ACCESS LEVEL
Conditional access support for commands or jobs entered into the system through a JES input device. INTRDR = Jobs submitted via Internal Reader as a result of executing JCL.

STCINRDR=Jobs submitted via Internal Reader as a result of the execution of a CICS or IMS transaction.

TSUINRDR = Jobs submitted via the ESMAC JES "Control" page and/or the cassub command line interface.

None, Read
JESJOBS
JES relation Entities ACCESS LEVEL
Controlling the submission and cancellation of jobs by job name.
CANCEL
nodename.userid.jobname (for job cancellation authority)
SUBMIT
nodename.jobname.userid (for job submissions)
where nodename is the name of the enterprise server.

These rules are not typically used, but they do provide granularity of control for those environments with special requirements.

NONE
Allows no access.
READ
Allows user to submit jobs
UPDATE
Equivalent to READ.
CONTROL
Equivalent to UPDATE.
ALTER
Allows jobs to be cancelled .
JESSPOOL
JES relation Entities ACCESS LEVEL
Controlling access to job data sets on the JES spool (Joblog, SYSOUT and Messages. localnodeid.userid.jobname.jobid.dsnumber.name

where

localnodeid
the name of the enterprise server
dsnumber
the relative dataset number for the job e.g. 001
name
the dd name

These rules are not typically used, but they do provide granularity of control for those environments with special requirements.

NONE
Allows no access.
READ
Allows user to view the spool data set, but not change its attributes. For example, this does not allow the following keywords on the OUTPUT command: NOKEEP, NOHOLD, DELETE, NEWCLASS, and DEST.
UPDATE
Allows to update a spool data set.
CONTROL
Equivalent to UPDATE.
ALTER
Allows any operand specified on the TSO OUTPUT command, including deleting and printing. Also, when specified for a discrete profile, allows the user to change the profile itself.
PHYSFILE
JES relation Entities ACCESS LEVEL
Controls access to the physical file when changes to the dataset are made.

See the usage notes at the end of this table.

Physical files None, Alter
SURROGAT
JES relation Entities ACCESS LEVEL
JES Class for controlling access to job submission by surrogates. If UserA wants to submit a job to run as UserB then he must have "Read" access to the SURROGAT class for entity UserB.SUBMIT execution-userid .SUBMIT

For example, if USERA is USERB's surrogate, Enterprise Server will check that USERA has read access for the entity, USERB.SUBMIT in the SURROGAT class.

None, Read

DATASET usage notes

Access rights to files within the dataset are enforced if you have a mainframe dialect Compiler directive set. To ensure that security is also applied if you are not using a mainframe dialect, set the FCDCAT and ASSIGN"EXTERNAL" compiler directives, then ensure files are not assigned dynamically or statically in a SELECT statement.

PHYSFILE usage notes

When a user with update access to a DATASET class makes changes, before the changes are applied to the physical file, the PHYSFILE class is checked for access rights. Changes are made only if the user has access rights to PHYSFILE.

For example, in ESMAC, user access to PHYSFILE is verified when a user creates a new file, and when the physical file name is changed. Changes are allowed only when the user has access rights to PHYSFILE.

If the PHYSFILE class does not exist, access is permitted. Note that in this case an access check will still be made (and if the Security Auditing feature is enabled, an access-denied audit record will be generated, unless the "allow unknown resources" option is enabled in the security configuration), but the JES engine treats a security result of "denied because resource class undefined" as an "allow" result.

Below is an example LDIF definition for PHYSFILE.

#########################
# RACF Class = PHYSFILE #
#########################
dn:CN=PHYSFILE,CN=Enterprise Server Resources,CN=MicroFocus,CN=RPIS,DC=mftesting,DC=com
changetype: add
objectClass: top
objectClass: container
description: JES Class for controlling access to physical files

#########################
# physical file MYFILE #
#########################
dn:CN=D\3A\\RPIS\\DATA\\MYFILE.DAT,CN=PHYSFILE,CN=Enterprise ServerResources,CN=Micro Focus,CN=RPIS,DC=mftesting,DC=com changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class:PHYSFILE
microfocus-MFDS-Resource-ACE: allow:ALLUSER group:alter
microfocus-MFDS-UID: mfuid
Parent topic: Resource Classes used by Enterprise Server


Resource Classes for IMS Security

The table below defines the name of each default resource class used in Enterprise Server for IMS security, its meaning, the type of resource entities it contains, and the minimum permission that a user requires on the entities.

IMS Class name | IMS relation | Entities | ACCESS LEVEL
TIMS | IMS transactions security class | Transactions | Read
CIMS | IMS Commands security class | IMS Commands | Read
FIMS | IMS Field-level sensitivity class | IMS Segments Fields | Update
IIMS | IMS PSB security class | IMS PSB access | Update
LIMS | IMS LTERM security class | IMS Logical terminals | Read
PIMS | IMS Database security class | IMS DBD access | Update
SIMS | IMS Segment-level security class | IMS Segments access | Update
OIMS | IMS Other items security class | IMS User defined security | Update
Parent topic: Resource Classes used by Enterprise Server


Resource Classes for ESMAC and Operator Command Security

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
Entity | Description
JESALIAS | If the user has 'Update' access to this resource, they are able to update or delete entries from the Alias table. If the user only has 'Read' access to this resource, the Update and Delete options are not available. If the user has 'None' access to this resource, they cannot access the Alias table at all.
Access Level
None, Read, or Update
MFESMAC
Relation
MAC Class for controlling access to ESMAC Resources

An attempt has been made to match the Entities listed below with the individual flags that are available for each user as defined in the old CICS Resource definition. For each "flag" there are three states: None, Read, Update.

Entities
Entity | Description
TABLE | This is the equivalent of the "Master" flag within the CICS RDT file. 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, and the list of currently active ACEEs. 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.
IMS | This controls access to the buttons under the Resources drop down when the IMS selection is utilized. See notes on GRP for details on the access rights.
JCL | This controls access to the buttons under the Resources drop down when the JES selection is utilized. See notes on GRP for details on the access rights.
DCT, DOC, FCT, ICE, JCT, MPR, PCT, PLT, PPT, SYS6, SYSC, TCP, TCT, TERM, TST, TTYPE, URI, XAT, XLT This controls the access a user has to the various resources (e.g. DCT, PCT, FCT) 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.

For example, if a user has READ access to PCT*, he or she will have the ability to view any PCTs defined to the system, but will not be able to update the entries. If the user has "Update" access then he or she can change and even install new ones. (assuming appropriate CINS authority)

The resources listed above also control access to specific pages. If for instance a page is primarily the DCT details for a DCT entry then attempting to access this page with no authority will result in your being driven to a "Sign-on" screen.

ENV

This controls whether a user has an access to view the environment variable settings of an enterprise server by enabling or disabling the Env. Vars. button or using a direct URL.

To use this entity, create a new element (ENV*) in the LDAP schema in the CN=MFESMAC group below CN=Enterprise Server Resources. Configure the group or the user access rights using the microfocus-MFDS-Resource-ACE attribute - set ACE=deny:SYSADM group:read (disables the Env. Vars. button in ESMAC) or ACE=allow:SYSADM group:read (enables Env. Vars. in ESMAC).

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

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

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


WebSphere MQ Switch Profiles

To control the security checking performed by WebSphere MQ, you must define switch profiles. A switch profile is a normal security profile that has a special meaning to WebSphere MQ. The access list in switch profiles is not used by WebSphere MQ.

When you set a security switch on, the security checks associated with the switch are performed. When you set a security switch off, the security checks associated with the switch are bypassed. The default is that all security switches are set on.

Parent topic: Resource Classes for WebSphere MQ


Switches and Classes

When an Enterprise Server region is started, the first access to WebSphere MQ checks the status of Security and the MQADMIN class. The subsystem security switch is set to off if one of these conditions are discovered:

  • Security is inactive
  • The MQADMIN class is not defined
  • The MQADMIN class has not been activated

If both Security and the MQADMIN class are active, WebSphere MQ checks the MQADMIN class to see whether any of the switch profiles have been defined. It first checks the profiles described in Profiles to control subsystem security. If subsystem security is not required, WebSphere MQ sets the internal subsystem security switch off, and performs no further checks.

The profiles determine whether the corresponding WebSphere MQ switch is set off and that the type of security is deactivated. If any WebSphere MQ switch is set on, WebSphere MQ checks the status of the Security class associated with the type of security corresponding to the WebSphere MQ switch. If the class is not installed or not active, the WebSphere MQ switch is set off. For example, process security checks are not carried out if the MQPROC class has not been activated. A non active class is equivalent to defining NO.PROCESS.CHECKS profile for every queue manager that uses the Security database.

Parent topic: Resource Classes for WebSphere MQ


How Switches Work

To set a security switch off, you need to define a NO.* switch profile. The existence of a NO.* profile means that security checks are not performed for that type of resource.

Each NO.* switch profile that WebSphere MQ detects turns off the checking for that type of resource. Switch profiles are activated during startup of the queue manager. If you change the switch profiles while any affected Enterprise Server Regions are running, you will need to restart the region for the new values to take effect.

The switch profiles must always be defined in the MQADMIN class.

Parent topic: Resource Classes for WebSphere MQ


Profiles to Control Subsystem Security

The first security check made by WebSphere MQ is used to determine whether security checks are required for the whole WebSphere MQ subsystem. If you specify that you do not want subsystem security, no further checks are made.

The following table shows the switch profiles that are checked to determine whether subsystem security is required.

Switch profile name | Type of resource or checking that is controlled
qmgr-name.NO.SUBSYS.SECURITY | Subsystem security for this queue manager. If not found, then security is on.
qmgr-name.YES.SUBSYS.SECURITY | Subsystem security for this queue manager (Default).
Parent topic: Resource Classes for WebSphere MQ


Profiles to Control Queue Manager Level Security

When WebSphere MQ has established that security checking is required, it then determines whether checking is required at queue manager level.

The following table shows the switch profiles are checked to determine the level required.

Switch profile name | Type of resource or checking that is controlled
qmgr-name.NO.QMGR.CHECKS | No queue manager level checks for this queue manager.
qmgr-name.YES.QMGR.CHECKS | Queue manager level checks override for this queue manager.
Parent topic: Resource Classes for WebSphere MQ


Valid Combinations of Switches

The following table shows the combinations of switch settings that are valid.

Security level | Switch settings
Queue manager level security | qmgr-name.NO.QMGR.CHECKS
 | qmgr-name.YES.QMGR.CHECKS
Parent topic: Resource Classes for WebSphere MQ


Resource Level Checks

The following table shows the switch profiles used to control access to WebSphere MQ resources.

Type of resource checking that is controlled | Switch profile name
Alternate user security | qmgr-name.YES.ALTERNATE.USER.CHECKS
Connection security | qmgr-name.YES.CONNECT.CHECKS
Context security | qmgr-name.YES.CONTEXT.CHECKS
Process security | qmgr-name.YES.PROCESS.CHECKS
Queue security | qmgr-name.YES.QUEUE.CHECKS

For example, if you wanted to perform process security checks on queue manager QM_nwb_magd820, you would define the following switch profile:

QM_nwb_magd820.YES.PROCESS.CHECKS

If you wanted to perform queue security checks on QM_nwb_magd820, you would define the following switch profile:

QM_nwb_magd820.YES.QUEUE.CHECKS
Note:

Generic switch profiles such as qmgr-name.YES.** are ignored by Enterprise Server

Note:

If the switch is not found, security checks will be performed by default, and messages will appear on the console.log as:

CASKC0033I WebSphere MQ !QM_nwb_magd820 SUBSYSTEM security switch set ON, profile 'QM_NWB_MAGD820.NO.SUBSYS.SECURITY' not found
CASKC0034I WebSphere MQ !QM_nwb_magd820 CONNECTION security switch set ON, profile 'QM_NWB_MAGD820.NO.CONNECT.CHECKS' not found
CASKC0034I WebSphere MQ !QM_nwb_magd820 PROCESS security switch set ON, profile 'QM_NWB_MAGD820.NO.PROCESS.CHECKS' not found
CASKC0034I WebSphere MQ !QM_nwb_magd820 CONTEXT security switch set ON, profile 'QM_NWB_MAGD820.NO.CONTEXT.CHECKS' not found
CASKC0034I WebSphere MQ !QM_nwb_magd820 QUEUE security switch set ON, profile 'QM_NWB_MAGD820.NO.QUEUE.CHECKS' not found
CASKC0034I WebSphere MQ !QM_nwb_magd820 ALTERNATE security switch set ON, profile 'QM_NWB_MAGD820NO.ALTERNATE.USER.CHECKS' not found
Parent topic: Resource Classes for WebSphere MQ


Profiles for Connection Security

If connection security is active, you must define profiles in the MQCONN class and permit the necessary groups or user IDs access to those profiles, so that they can connect to WebSphere MQ subsystems.

To enable a connection to be made, you must grant users READ access to the appropriate profile.

A connection profile qualified with a queue manager name controls access to a specific queue manager and users given access to this profile can connect to that queue manager.

For example, a user with access to QM_nwb_magd820.BATCH can Batch connect to queue manager QM_nwb_magd820.

Parent topic: Resource Classes for WebSphere MQ


Connection Security Profiles for the Batch/TSO adapter

Profiles for checking connections from Batch or TSO take the form:

qmgr-name.BATCH

where qmgr-name is the queue manager name. If it fails to find the profile, the connection request fails.

For connection requests through Batch or TSO, you must permit the job or TSO user ID to access the connection profile. For example, the following security definition allows Batch and TSO users in the ALLUSER group to connect to the queue manager QM_nwb_magd820:

#####################################
# MQCONN QM_nwb_magd820.BATCH auths #
#####################################
dn: CN=QM_nwb_magd820.BATCH,CN=MQCONN,CN=Enterprise Server Resources,CN=Micro Focus,DC=local
changetype: delete

dn: CN=QM_nwb_magd820.BATCH,CN=MQCONN,CN=Enterprise Server Resources,CN=Micro Focus,DC=local
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: MQCONN
microfocus-MFDS-Resource-ACE: allow:ALLUSER group:read
microfocus-MFDS-Resource-ACE: deny:*:execute
microfocus-MFDS-UID: mfuid
description: Enable security on MQCONN subsystem BATCH for QMGR QM_nwb_magd820
Parent topic: Resource Classes for WebSphere MQ


Connection Security Profiles for the CICS Adapter

Profiles for checking connections from CICS take the form:

qmgr-name.CICS

where qmgr-name is the queue manager name. If it fails to find the profile, the connection request fails.

For connection requests by CICS, you need only permit the CICS address space user ID access to the connection profile.

For example, the following Security definitions allow the CICS address space user ID SYSAD to connect to the queue manager QM_nwb_magd820

#####################################
# MQCONN QM_nwb_magd820.CICS auths  #
#####################################
dn: CN=QM_nwb_magd820.CICS,CN=MQCONN,CN=Enterprise Server Resources,CN=Micro Focus,DC=local
changetype: delete

dn: CN=QM_nwb_magd820.CICS,CN=MQCONN,CN=Enterprise Server Resources,CN=Micro Focus,DC=local
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: MQCONN
microfocus-MFDS-Resource-ACE: allow:SYSAD:read
microfocus-MFDS-Resource-ACE: deny:*:execute
microfocus-MFDS-UID: mfuid
description: Enable security on MQCONN subsystem CICS for QMGR QM_nwb_magd820
Parent topic: Resource Classes for WebSphere MQ


Connection Security Profiles for the IMS Adapter

Profiles for checking connections from IMS take the form:

qmgr-name.IMS

where qmgr-name is the queue manager name. If it fails to find the profile, the connection request fails.

Parent topic: Resource Classes for WebSphere MQ


Profiles for Queue Security

If queue security is active, you must define profiles in the MQQUEUE class and permit the necessary groups or user IDs access to these profiles, so they can issue WebSphere MQ API requests that use queues.

Profiles for queue security take the form:

qmgr-name.queuename

where qmgr-name (queue manager name) and queuename is the name of the queue being opened, as specified in the object descriptor on the MQOPEN or MQPUT1 call.

A profile prefixed by the queue manager name controls access to a single queue on that queue manager.

The RACF access required to open a queue depends on the MQOPEN or MQPUT1 options specified. If more than one of the MQOO_* and MQPMO_* options are coded, the queue security check is performed for the highest RACF authority required.

TMQOPEN or MQPUT1 option | RACF access level required to access qmgr-name.queuename
MQOO_BIND_* | UPDATE
MQOO_BROWSE | READ
MQOO_INPUT_* | UPDATE
MQOO_INQUIRE | READ
MQOO_OUTPUT or MQPUT1 | UPDATE
MQOO_PASS_ALL_CONTEXT | UPDATE
MQOO_PASS_IDENTITY_CONTEXT | UPDATE
MQOO_SAVE_ALL_CONTEXT | UPDATE
MQOO_SET | ALTER
MQOO_SET_ALL_CONTEXT | UPDATE
MQOO_SET_IDENTITY_CONTEXT | UPDATE
MQPMO_PASS_ALL_CONTEXT | UPDATE
MQPMO_PASS_IDENTITY_CONTEXT | UPDATE
MQPMO_SET_ALL_CONTEXT | UPDATE
MQPMO_SET_IDENTITY_CONTEXT | UPDATE
Parent topic: Resource Classes for WebSphere MQ


Process Profiles

If process security is active, you must define profiles in the MQPROC class, and permit access to the necessary groups or user IDs so they can use MQI requests that use processes. Profiles for processes take the form:

qmgr-name.processname

where qmgr-name (queue manager name) and processname is the name of the process being opened.

A profile prefixed by the queue manager name controls access to a single process definition on that queue manager.

The following table shows the access required for opening a process.

MQOPEN option | RACF access level required to qmgr-name.processname
MQOO_INQUIRE | READ
Parent topic: Resource Classes for WebSphere MQ


Profiles for Alternate User Security

If alternate user security is active, you must define profiles in the MQADMIN class and permit the necessary groups or user IDs access to these profiles, so that they can use the ALTERNATE_USER_AUTHORITY options when the object is opened.

Profiles for alternate user security can be specified at subsystem level and take the following form:

qmgr-name.ALTERNATE.USER.alternateuserid

where qmgr-name (queue manager name) and alternateuserid is the value of the AlternateUserId field in the object descriptor.

A profile prefixed by the queue manager name controls use of an alternate user ID on that queue manager.

The following table shows the access when specifying an alternate user option.

MQOPEN or MQPUT1 option | RACF access level required
MQOO_ALTERNATE_USER_AUTHORITY MQPMO_ALTERNATE_USER_AUTHORITY | UPDATE

In addition to alternate user security checks, other security checks for queue, process, and context security can also be made. The alternate user ID, if provided, is only used for security checks on queue and process definition. For alternate user and context security checks, the user ID requesting the check is used.

Parent topic: Resource Classes for WebSphere MQ


Profiles for Context Security

If context security is active, you must define a profile in the MQADMIN class called:

qmgr-name.CONTEXT

where qmgr-name (queue manager name).

A profile prefixed by the queue manager name allows control for context security on that queue manager.

You must give the necessary groups or user IDs access to this profile. The following table shows the access level required, depending on the specification of the context options, when the queue is opened.

MQOPEN or MQPUT1 option | RACF access level required to qmgr-name.CONTEXT
MQOO_OUTPUT or MQPUT1 (USAGE(XMITQ)) | CONTROL
MQOO_PASS_ALL_CONTEXT | READ
MQOO_PASS_IDENTITY_CONTEXT | READ
MQOO_SAVE_ALL_CONTEXT | No context security check
MQOO_SET_ALL_CONTEXT | CONTROL
MQOO_SET_IDENTITY_CONTEXT | UPDATE
MQPMO_DEFAULT_CONTEXT | No context security check
MQPMO_NO_CONTEXT | No context security check
MQPMO_PASS_ALL_CONTEXT | READ
MQPMO_PASS_IDENTITY_CONTEXT | READ
MQPMO_SET_ALL_CONTEXT | CONTROL
MQPMO_SET_IDENTITY_CONTEXT | UPDATE
Parent topic: Resource Classes for WebSphere MQ


CICS Resource and Command Checks

Note: Not all of the commands listed here are currently supported by Enterprise Server.
EXEC CICS COMMAND | Details of resource checking |  |  |  | Command security checking (default class CCICSCMD - governed by environment variable ES_CLASS_XCMD)
 | Default resource class name | Environment variable governing resource class | Resource | Type of access required | Resource | Type of access required
ACQUIRE |  |  |  |  | TERMINAL | UPDATE
ACQUIRE for BTS | FCICSFCT | ES_CLASS_XFCT | BTS repository file | UPDATE |  |
CANCEL | ACICSPCT | ES_CLASS_XPCT | transid | READ |  |
CANCEL for BTS | FCICSFCT | ES_CLASS_XFCT | BTS repository file | UPDATE |  |
COLLECT STATISTICS |  |  |  |  | STATISTICS | READ
COLLECT STATISTICS FILE | FCICSFCT | ES_CLASS_XFCT | file | READ | STATISTICS | READ
COLLECT STATISTICS JOURNALNAME | JCICSJCT | ES_CLASS_XJCT | journal | READ | STATISTICS | READ
COLLECT STATISTICS JOURNALNUM | JCICSJCT | ES_CLASS_XJCT | journal | READ | STATISTICS | READ
COLLECT STATISTICS PROGRAM | MCICSPPT | ES_CLASS_XPPT | program | READ | STATISTICS | READ
COLLECT STATISTICS TDQUEUE | ACICSPCT | ES_CLASS_XPCT | tdqueue | READ | STATISTICS | READ
COLLECT TRANSACTION | DCICSDCT | ES_CLASS_XDCT | transid | READ | STATISTICS | READ
CREATE CONNECTION |  |  |  |  | CONNECTION | ALTER
CREATE CORBASERVER |  |  |  |  | CORBASERVER | ALTER
CREATE DJAR |  |  |  |  | DJAR | ALTER
CREATE DOCTEMPLATE | RCICSRES | ES_CLASS_XRES |  | ALTER | DOCTEMPLATE | ALTER
CREATE ENQMODEL |  |  |  |  | ENQMODEL | ALTER
CREATE FILE | FCICSFCT | ES_CLASS_XFCT | file | ALTER | FILE | ALTER
CREATE JOURNALMODEL |  |  |  |  | JOURNALMODEL | ALTER
CREATE LSRPOOL |  |  |  |  | LSRPOOL | ALTER
CREATE MAPSET | MCICSPPT | ES_CLASS_XPPT | mapset | ALTER | MAPSET | ALTER
CREATE PARTITIONSET | MCICSPPT | ES_CLASS_XPPT | partitionset | ALTER | PARTITIONSET | ALTER
CREATE PIPELINE |  |  |  |  | PIPELINE | ALTER
CREATE PARTNER |  |  |  |  | PARTNER | ALTER
CREATE PROCESSTYPE |  |  |  |  | PROCESSTYPE | ALTER
CREATE PROFILE |  |  |  |  | PROFILE | ALTER
CREATE PROGRAM | MCICSPPT | ES_CLASS_XPPT | program | ALTER | PROGRAM | ALTER
CREATE REQUESTMODEL |  |  |  |  | REQUESTMODEL | ALTER
CREATE SESSIONS |  |  |  |  | SESSIONS | ALTER
CREATE TCPIPSERVICE |  |  |  |  | TCPIPSERVICE | ALTER
CREATE TDQUEUE | DCICSDCT | ES_CLASS_XDCT | tdqueue | ALTER | TDQUEUE | ALTER
CREATE TERMINAL |  |  |  |  | TERMINAL | ALTER
CREATE TRANCLASS |  |  |  |  | TCLASS | ALTER
CREATE TRANSACTION | ACICSPCT | ES_CLASS_XPCT | transid | ALTER | TRANSACTION | ALTER
CREATE TSMODEL |  |  |  |  | TSMODEL | ALTER
CREATE TYPETERM |  |  |  |  | TYPETERM | ALTER
CREATE URIMAP |  |  |  |  | URIMAP | ALTER
CREATE WEBSERVICE |  |  |  |  | WEBSERVICE | ALTER
DEFINE ACTIVITY | FCICSFCT | ES_CLASS_XFCT | BTS repository file | UPDATE |  |
DEFINE PROCESS | FCICSFCT | ES_CLASS_XFCT | BTS repository file | UPDATE |  |
DELETE | FCICSFCT | ES_CLASS_XFCT | file | UPDATE |  |
DELETE ACTIVITY | FCICSFCT | ES_CLASS_XFCT | BTS repository file | UPDATE |  |
DELETEQ TD | DCICSDCT | ES_CLASS_XDCT | tdqueue | UPDATE |  |
DELETEQ TS | SCICSTST | ES_CLASS_XTST | tsqueue | UPDATE |  |
DISABLE PROGRAM | MCICSPPT | ES_CLASS_XPPT | program | UPDATE | EXITPROGRAM | UPDATE
DISCARD AUTINSTMODEL |  |  |  |  | AUTINSTMODEL | ALTER
DISCARD CORBASERVER |  |  |  |  | CORBASERVER | ALTER
DISCARD DJAR |  |  |  |  | DJAR | ALTER
DISCARD DOCTEMPLATE | RCICSRES | ES_CLASS_XRES |  | ALTER | DOCTEMPLATE | ALTER
DISCARD ENQMODEL |  |  |  |  | ENQMODEL | ALTER
DISCARD FILE | FCICSFCT | ES_CLASS_XFCT | file | ALTER | FILE | ALTER
DISCARD JOURNALMODEL |  |  |  |  | JOURNALMODEL | ALTER
DISCARD JOURNALNAME | JCICSJCT | ES_CLASS_XJCT | journal | ALTER | JOURNALNAME | ALTER
DISCARD PARTNER |  |  |  |  | PARTNER | ALTER
DISCARD PIPELINE |  |  |  |  | PIPELINE | ALTER
DISCARD PROCESSTYPE |  |  |  |  | PROCESSTYPE | ALTER
DISCARD PROFILE |  |  |  |  | PROFILE | ALTER
DISCARD PROGRAM | MCICSPPT | ES_CLASS_XPPT | program | ALTER | PROGRAM | ALTER
DISCARD REQUESTMODEL |  |  |  |  | REQUESTMODEL | ALTER
DISCARD TCPIPSERVICE |  |  |  |  | TCPIPSERVICE | ALTER
DISCARD TDQUEUE | DCICSDCT | ES_CLASS_XDCT | tdqueue | ALTER | TDQUEUE | ALTER
DISCARD TERMINAL |  |  |  |  | TERMINAL | ALTER
DISCARD TRANCLASS |  |  |  |  | TCLASS | ALTER
DISCARD TRANSACTION | ACICSPCT | ES_CLASS_XPCT | transid | ALTER | TRANSACTION | ALTER
DISCARD TSMODEL |  |  |  |  | TSMODEL | ALTER
DISCARD URIMAP |  |  |  |  | URIMAP | ALTER
DISCARD WEBSERVICE |  |  |  |  | WEBSERVICE | ALTER
DOCUMENT |  |  |  |  | DOCUMENT |
ENABLE PROGRAM | MCICSPPT | ES_CLASS_XPPT | program | UPDATE | EXITPROGRAM | UPDATE
EXTRACT EXIT | MCICSPPT | ES_CLASS_XPPT | program | READ | EXITPROGRAM | UPDATE
EXTRACT STATISTICS |  |  |  |  | STATISTICS | READ
FEPI |  |  |  |  | FEPI |
HANDLE ABEND PROGRAM | MCICSPPT | ES_CLASS_XPPT | program | READ |  |
INQUIRE ACTIVITYID | FCICSFCT | ES_CLASS_XFCT | BTS repository file | READ |  |
INQUIRE AUTINSTMODEL |  |  |  |  | AUTINSTMODEL | READ
INQUIRE AUTOINSTALL |  |  |  |  | AUTOINSTALL | READ
INQUIRE BEAN |  |  |  |  | BEAN | READ
INQUIRE BRFACILITY |  |  |  |  | BRFACILITY | READ
INQUIRE CFDTPOOL |  |  |  |  | CFDTPOOL | READ
INQUIRE CLASSCACHE |  |  |  |  | CLASSCACHE | READ
INQUIRE CONNECTION |  |  |  |  | CONNECTION | READ
INQUIRE CORBASERVER |  |  |  |  | CORBASERVER | READ
INQUIRE CONTAINER | FCICSFCT | ES_CLASS_XFCT | BTS repository file | READ |  |
INQUIRE DELETSHIPPED |  |  |  |  | DELETSHIPPED | READ
INQUIRE DJAR |  |  |  |  | DJAR | READ
INQUIRE DOCTEMPLATE | RCICSRES | ES_CLASS_XRES |  | READ | DOCTEMPLATE | READ
INQUIRE DSNAME |  |  |  |  | DSNAME | READ
INQUIRE DUMPDS |  |  |  |  | DUMPDS | READ
INQUIRE ENQMODEL |  |  |  |  | ENQMODEL | READ
INQUIRE EXCI |  |  |  |  | EXCI | READ
INQUIRE EVENT | FCICSFCT | ES_CLASS_XFCT | BTS repository file | READ |  |
INQUIRE EXITPROGRAM | MCICSPPT | ES_CLASS_XPPT | program | READ | EXITPROGRAM | READ
INQUIRE FILE | FCICSFCT | ES_CLASS_XFCT | file | READ | FILE | READ
INQUIRE HOST |  |  |  |  | HOST | READ
INQUIRE IRC |  |  |  |  | IRC | READ
INQUIRE JOURNALMODEL |  |  |  |  | JOURNALMODEL | READ
INQUIRE JOURNALNAME | JCICSJCT | ES_CLASS_XJCT | journal | READ | JOURNAL | READ
INQUIRE JVM |  |  |  |  | JVM | READ
INQUIRE JVMPOOL |  |  |  |  | JVMPOOL | READ
INQUIRE JVMPROFILE |  |  |  |  | JVMPROFILE | READ
INQUIRE MODENAME |  |  |  |  | MODENAME | READ
INQUIRE MONITOR |  |  |  |  | MONITOR | READ
INQUIRE MVSTCB |  |  |  |  | MVSTCB | READ
INQUIRE NETNAME |  |  |  |  | TERMINAL | READ
INQUIRE PARTNER |  |  |  |  | PARTNER | READ
INQUIRE PIPELINE |  |  |  |  | PIPELINE | READ
INQUIRE PROCESS | FCICSFCT | ES_CLASS_XFCT | BTS repository file | READ |  |
INQUIRE PROCESSTYPE |  |  |  |  | PROCESSTYPE | READ
INQUIRE PROFILE |  |  |  |  | PROFILE | READ
INQUIRE PROGRAM | MCICSPPT | ES_CLASS_XPPT | program | READ | PROGRAM | READ
INQUIRE REQID | ACICSPCT | ES_CLASS_XPCT | transid | READ | REQID | READ
INQUIRE REQUESTMODEL |  |  |  |  | REQUESTMODEL | READ
INQUIRE RRMS |  |  |  |  | RRMS | READ
INQUIRE STATISTICS |  |  |  |  | STATISTICS | READ
INQUIRE STORAGE |  |  |  |  | STORAGE | READ
INQUIRE STREAMNAME |  |  |  |  | STREAMNAME | READ
INQUIRE SUBPOOL |  |  |  |  | SUBPOOL | READ
INQUIRE SYSDUMPCODE |  |  |  |  | SYSDUMPCODE | READ
INQUIRE SYSTEM |  |  |  |  | SYSTEM | READ
INQUIRE TASK |  |  |  |  | TASK | READ
INQUIRE TCLASS |  |  |  |  | TCLASS | READ
INQUIRE TCPIP |  |  |  |  | TCPIP | READ
INQUIRE TCPIPSERVICE |  |  |  |  | TCPIPSERVICE | READ
INQUIRE TDQUEUE | DCICSDCT | ES_CLASS_XDCT | tdqueue | READ | TDQUEUE | READ
INQUIRE TERMINAL |  |  |  |  | TERMINAL | READ
INQUIRE TIMER | FCICSFCT | ES_CLASS_XFCT | BTS repository file | READ |  |
INQUIRE TRACEDEST |  |  |  |  | TRACEDEST | READ
INQUIRE TRACEFLAG |  |  |  |  | TRACEFLAG | READ
INQUIRE TRACETYPE |  |  |  |  | TRACETYPE | READ
INQUIRE TRANCLASS |  |  |  |  | TCLASS | READ
INQUIRE TRANDUMPCODE |  |  |  |  | TRANDUMPCODE | READ
INQUIRE TRANSACTION | ACICSPCT | ES_CLASS_XPCT | program | READ | TRANSACTION | READ
INQUIRE TSMODEL |  |  |  |  | TSMODEL | READ
INQUIRE TSPOOL |  |  |  |  | TSPOOL | READ
INQUIRE TSQUEUE | SCICSTST | ES_CLASS_XTST | tsqueue | READ | TSQUEUE | READ
INQUIRE TSQNAME | SCICSTST | ES_CLASS_XTST | tsqname | READ | TSQUEUE | READ
INQUIRE UOW |  |  |  |  | UOW | READ
INQUIRE UOWDSNFAIL |  |  |  |  | UOWDSNFAIL | READ
INQUIRE UOWENQ |  |  |  |  | UOWENQ | READ
INQUIRE UOWLINK |  |  |  |  | UOWLINK | READ
INQUIRE URIMAP |  |  |  |  | URIMAP | READ
INQUIRE VTAM |  |  |  |  | VTAM | READ
INQUIRE WEB |  |  |  |  | WEB | READ
INQUIRE WEBSERVICE |  |  |  |  | WEBSERVICE | READ
INQUIRE WORKREQUEST |  |  |  |  | WORKREQUEST | READ
LINK | MCICSPPT | ES_CLASS_XPPT | program | READ |  |
LINK ACQPROCESS | FCICSFCT | ES_CLASS_XFCT | BTS repository file | UPDATE |  |
LINK ACTIVITY / ACQACTIVITY | FCICSFCT | ES_CLASS_XFCT | BTS repository file | UPDATE |  |
LOAD | MCICSPPT | ES_CLASS_XPPT | program | READ |  |
PERFORM CLASSCACHE |  |  |  |  | CLASSCACHE | UPDATE
PERFORM CORBASERVER |  |  |  |  | CORBASERVER | UPDATE
PERFORM DELETSHIPPED |  |  |  |  | DELETSHIPPED | UPDATE
PERFORM DJAR |  |  |  |  | DJAR | UPDATE
PERFORM DUMP |  |  |  |  | DUMP | UPDATE
PERFORM PIPELINE |  |  |  |  | PIPELINE | UPDATE
PERFORM RESETTIME |  |  |  |  | RESETTIME | UPDATE
PERFORM SECURITY |  |  |  |  | SECURITY | UPDATE
PERFORM SHUTDOWN |  |  |  |  | SHUTDOWN | UPDATE
PERFORM STATISTICS |  |  |  |  | STATISTICS | UPDATE
READ | FCICSFCT | ES_CLASS_XFCT | file | READ |  |
READQ TD | DCICSDCT | ES_CLASS_XDCT | tdqueue | UPDATE |  |
READQ TS | SCICSTST | ES_CLASS_XTST | tsqueue | READ |  |
RELEASE | MCICSPPT | ES_CLASS_XPPT | program | READ |  |
RESET ACTIVITY | FCICSFCT | ES_CLASS_XFCT | BTS repository file | UPDATE |  |
RESET ACQPROCESS | FCICSFCT | ES_CLASS_XFCT | BTS repository file | UPDATE |  |
RESYNC ENTRYNAME |  |  |  |  | EXITPROGRAM | UPDATE
RETURN / RETURN ENDACTIVITY | FCICSFCT | ES_CLASS_XFCT | BTS repository file | UPDATE |  |
REWRITE | FCICSFCT | ES_CLASS_XFCT | file | UPDATE |  |
RUN | FCICSFCT | ES_CLASS_XFCT | BTS repository file | UPDATE |  |
RUN / ASYNCH SYNC | FCICSFCT | ES_CLASS_XFCT | DFHLRQ file | UPDATE |  |
SET AUTOINSTALL |  |  |  |  | AUTOINSTALL | UPDATE
SET BRFACILITY |  |  |  |  | BRFACILITY | UPDATE
SET CLASSCACHE |  |  |  |  | CLASSCACHE | UPDATE
SET CONNECTION |  |  |  |  | CONNECTION | UPDATE
SET CORBASERVER |  |  |  |  | CORBASERVER | UPDATE
SET DELETSHIPPED |  |  |  |  | DELETSHIPPED | UPDATE
SET DOCTEMPLATE | RCICSRES | ES_CLASS_XRES |  | UPDATE | DOCTEMPLATE | UPDATE
SET DSNAME |  |  |  |  | DSNAME | UPDATE
SET DUMPDS |  |  |  |  | DUMPDS | UPDATE
SET ENQMODEL |  |  |  |  | ENQMODEL | UPDATE
SET FILE | FCICSFCT | ES_CLASS_XFCT | file | UPDATE | FILE | UPDATE
SET HOST |  |  |  |  | HOST | UPDATE
SET IRC |  |  |  |  | IRC | UPDATE
SET JOURNALNAME | JCICSJCT | ES_CLASS_XJCT | journal | UPDATE | JOURNAL | UPDATE
SET JVMPOOL |  |  |  |  | JVMPOOL | UPDATE
SET MODENAME |  |  |  |  | MODENAME | UPDATE
SET MONITOR |  |  |  |  | MONITOR | UPDATE
SET NETNAME |  |  |  |  | TERMINAL | UPDATE
SET PIPELINE |  |  |  |  | PIPELINE | UPDATE
SET PROGRAM | MCICSPPT | ES_CLASS_XPPT | program | UPDATE | PROGRAM | UPDATE
SET REQUESTMODEL |  |  |  |  | REQUESTMODEL | UPDATE
SET STATISTICS |  |  |  |  | STATISTICS | UPDATE
SET SYSDUMPCODE |  |  |  |  | SYSDUMPCODE | UPDATE
SET SYSTEM |  |  |  |  | SYSTEM | UPDATE
SET TASK |  |  |  |  | TASK | UPDATE
SET TCLASS |  |  |  |  | TCLASS | UPDATE
SET TCPIP |  |  |  |  | TCPIP | UPDATE
SET TCPIPSERVICE |  |  |  |  | TCPIPSERVICE | UPDATE
SET TDQUEUE | DCICSDCT | ES_CLASS_XDCT | tdqueue | UPDATE | TDQUEUE | UPDATE
SET TERMINAL |  |  |  |  | TERMINAL | UPDATE
SET TRACEDEST |  |  |  |  | TRACEDEST | UPDATE
SET TRACEFLAG |  |  |  |  | TRACEFLAG | UPDATE
SET TRACETYPE |  |  |  |  | TRACETYPE | UPDATE
SET TRANCLASS |  |  |  |  | TCLASS | UPDATE
SET TRANDUMPCODE |  |  |  |  | TRANDUMPCODE | UPDATE
SET TRANSACTION | ACICSPCT | ES_CLASS_XPCT | transid | UPDATE | TRANSACTION | UPDATE
SET TSMODEL |  |  |  |  | TSMODEL | UPDATE
SET TSQNAME | SCICSTST | ES_CLASS_XTST | tsqueue | UPDATE | TSQUEUE | UPDATE
SET TSQUEUE | SCICSTST | ES_CLASS_XTST | tsqname | UPDATE | TSQUEUE | UPDATE
SET UOW |  |  |  |  | UOW | UPDATE
SET UOWLINK |  |  |  |  | UOWLINK | UPDATE
SET URIMAP |  |  |  |  | URIMAP | UPDATE
SET VTAM |  |  |  |  | VTAM | UPDATE
SET WEB |  |  |  |  | WEB | UPDATE
SET WEBSERVICE |  |  |  |  | WEBSERVICE | UPDATE
SET WORKREQUEST |  |  |  |  | WORKREQUEST | UPDATE
START | ACICSPCT | ES_CLASS_XPCT | transid | READ |  |
STARTBR | FCICSFCT | ES_CLASS_XFCT | file | READ |  |
STARTBROWSE ACTIVITY | FCICSFCT | ES_CLASS_XFCT | BTS repository file | READ |  |
STARTBROWSE CONTAINER (BTS) | FCICSFCT | ES_CLASS_XFCT | BTS repository file | READ |  |
STARTBROWSE EVENT | FCICSFCT | ES_CLASS_XFCT | BTS repository file | READ |  |
STARTBROWSE PROCESS | FCICSFCT | ES_CLASS_XFCT | BTS repository file | READ |  |
SUSPEND | FCICSFCT | ES_CLASS_XFCT | BTS repository file | UPDATE |  |
WAIT JOURNALNAME | JCICSJCT | ES_CLASS_XJCT | journal | READ |  |
WAIT JOURNALNUM | JCICSJCT | ES_CLASS_XJCT | journal | READ |  |
WRITE | FCICSFCT | ES_CLASS_XFCT | file | UPDATE |  |
WRITE JOURNALNAME | JCICSJCT | ES_CLASS_XJCT | journal | UPDATE |  |
WRITE JOURNALNUM | JCICSJCT | ES_CLASS_XJCT | DFHJnn | UPDATE |  |
WRITEQ TD | DCICSDCT | ES_CLASS_XDCT | tdqueue | UPDATE |  |
WRITEQ TS | SCICSTST | ES_CLASS_XTST | tsqueue or tsqname | UPDATE |  |
XCTL | MCICSPPT | ES_CLASS_XPPT | program | READ |  |
Parent topic: Resource Classes used by Enterprise Server


Solutions, Restrictions, and Changes in Behavior

  • Service Deployment and Security
  • Restrictions on usernames and passwords
  • Restricting JCL submission
  • Configuring Credentials for Starting and Stopping Enterprise Servers
  • Timeouts for Terminal Users
  • Sign-on Disabled for Default Users
  • Configuring Sun Java System Directory as a Security Manager
Parent topic: Security Reference Information


Service Deployment and Security

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


Restrictions on usernames and passwords

Usernames longer than eight characters cannot be used for MSS. This includes using them to start an enterprise server. As a consequence, if an MF Directory Server administrator signs on with a username that is longer than eight characters, he or she will have to supply a different username when starting an enterprise server from the Enterprise Server Administration screens.

This restriction also applies to JES and JCL support. Any name referenced in JCL must be uppercase (e.g. USER=XXX), as you cannot use a lower-case or mixed-case username in JCL. You can however have a user with a lower- or mixed-case name to submit jobs.

Important: For reasons of mainframe compatibility and technical limitations, many components of Enterprise Server are limited to a maximum of eight ASCII characters for user IDs and passwords. To avoid issues with user sign-on and similar functions, avoid attempting to create user IDs or passwords that do not meet this requirement.
Parent topic: Solutions, Restrictions, and Changes in Behavior


Restricting JCL submission

In order to disable the JCL Submit button in ESMAC for a group of users, but still allow them to submit JCL using the cassub command line utility, the LDAP security repository requires a read access rule for the "CN=cassub,CN=OPERCMDS,CN=Enterprise Server Resources" resource class authorization.

dn: CN=cassub,CN=OPERCMDS,CN=Enterprise Server Resources
microfocus-MFDS-Resource-ACE: allow:<group-name> group:read

<group-name> must be followed by a space and the word “group” for group access authority.

Parent topic: Solutions, Restrictions, and Changes in Behavior


Configuring Credentials for Starting and Stopping Enterprise Servers

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


Timeouts for Terminal Users

If a user is connected to a tn3270 terminal, and an ID timeout is specified either at the user level or at the system level (that is, the value specified in the SIT or overridden on the ESMAC Control page), then when the timeout is reached the user will be automatically signed-off and the default transaction specified in the SIT will be started.

Values are specified in minutes. If the value specified for the user is 0, the system timeout value is used. If the value specified for the user is -62, the user is never timed-out, irrespective of the system value. If any other value is specified for the user, that value is used in preference to the system value.

Note:

Note that Terminal timeouts (SIT parameter or user ID parameter) must be less than 16 hours.

Parent topic: Solutions, Restrictions, and Changes in Behavior


Sign-on Disabled for Default Users

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

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


Using External Security Facility (ESF) Features

ESF comprises:

  • OS ESM Module
  • ESF Caching
  • External Administrative Update Notification
  • ESF Passtokens
  • Security Federation
  • ESF Manager Messages and Logging
  • ESF User Exit
  • The Referential Integrity Sample User Exit
  • Result Codes in the ESF API Parameter Block
Parent topic: Securing an Enterprise Server Installation


OS ESM Module

The OS ESM Module lets users sign in to ESF-protected systems (Enterprise Server regions and MFDS) using their operating system username and password. (Currently OS ESM is supported only on Windows.) When OS ESM is used, users sign on to MFDS, ESMAC, and/or MTO (depending on your security configuration) with their Windows username and password.

By default OS ESM 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 (see the configuration section below).

Note, though, that OS ESM is limited to what Windows normally allows; it cannot verify a user in a domain that is not trusted by the local system. Basically, you should be able to sign on to any domain that's listed in your Windows sign-on dialog.

The OS ESM itself has support for domain\username syntax and UPN usernames (username@domain.tld), but the sign-on screens for MFDS and MTO do not currently support them, so they cannot be used in this version of Enterprise Server.

The OS ESM supports ESF Passtokens, which can be used to automatically pass credentials between MFDS and ESMAC, if both MFDS and Enterprise Server are configured to use OS ESM.

  • Resource Access Control
  • Module Configuration
Parent topic: Using External Security Facility (ESF) Features
Related concepts
Module Configuration
ESF Passtokens


Resource Access Control

OS ESM only supports the Verify operation (user sign-on). It does not do any resource access control (the Auth and XAuth operations), so if you want to control access to resources for signed-on users, you will need to configure another ESM Module for that purpose.

This is called stacking ESM Modules. For each ESF request, the modules are called in turn until one of them handles the request. If you stack the OS ESM module first and another ESM Module, such as the MLDAP ESM Module, after it, then Verify (sign-on) requests will be handled by OS ESM. But since OS ESM doesn't handle Auth (resource access) requests, those will go through to the second ESM Module.

To stack the OS ESM with another ESM Module, use the MFDS administration GUI to update your security configuration. First create two Security Managers, one for each ESM Module, if you don't already have them. Then edit the appropriate security configuration (the Default Enterprise Server Security, the MFDS Security, or the security configuration for a specific Enterprise Server region) and add both of your security managers to it. Make sure the OS ESM security manager is first in the list; if not, use the arrow buttons to change the order of the managers in the list.

Parent topic: OS ESM Module
Related concepts
Access Levels and Permissions
MLDAP ESM Module
Resource Access Control Lists


Module Configuration

Because OS ESM uses the operating system to authenticate user credentials, it doesn't have many configuration parameters.

To select the OS ESM Module for a Security Manager, set the Module field to osesm. If the Enabled checkbox is unchecked, ESF Manager will not load or use this security configuration. The other fields are not used with OS ESM.

  • OS ESM Module Custom Configuration Information
Parent topic: OS ESM Module


OS ESM Module Custom Configuration Information

The OS ESM 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 in the form name=value.

Here are the various configuration sections, and the options that can be set in each section.

[Operation] section

domain=domain
Set 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
Set 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 fewer resources. However, it requires that the user have 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
Set 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 MFDS and ESMAC, 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 Enterprise Server 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
Set 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 Enterprise Server regions) that will exchange passtokens.
secret file=path
Set 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
Set 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: Module Configuration
Related concepts
ESF Passtokens


ESF Caching

ESF supports caching (remembering) the results of some security requests. This can improve performance, sometimes dramatically, by eliminating some calls to the configured Security Managers.

There are two types of ESF caching. The ESF manager itself can cache results. When a request matches one in the ESF cache, the ESM Modules are not called, and the cached result is returned. ESF also has a mechanism for ESM Modules to cache information that may be expensive to retrieve, but currently no ESM Modules make use of that feature. That means caching is only active if it is enabled in the ESF configuration, not in the security manager configuration.

  • What is Cached?
  • Enabling and Configuring Caching
Parent topic: Using External Security Facility (ESF) Features


What is Cached?

By default, ESF caching is disabled. If you enable caching, then by default the results of Auth and XAuth requests (resource access requests) are cached, when the result is either "explicitly allowed" or "explicitly denied". Auth/XAuth requests that result in an "unknown" status, because no ESM has a rule that governs that access request, are not cached, regardless of whether the access is ultimately granted. (The setting of the "Allow unknown resources" option in the ESF configuration determines how those requests are handled.)

Also, Verify (user sign-on) requests are not cached by default, even when caching is enabled.

There are advanced configuration settings you can use to enable or disable the caching of particular types of requests. Some requests can never be cached, including Verify requests that involve passtokens.

  • Caching and Side Effects
  • Using Flush on Change
Parent topic: ESF Caching
Related concepts
Enabling and Configuring Caching
Advanced Configuration
ESF Passtokens


Caching and Side Effects

When a request is processed by retrieving an entry from the cache, it is not passed to the ESM Modules, which means it is not seen by the ESM. Sometimes ESMs do more than simply allow or deny security requests. These are called "side effects". For example, some ESMs keep track of the last time a user logged in; that's a side effect. If a Verify request is answered from the cache, the ESM will not be told to update the last-login time.

Side effects are commonly used with Verify requests, which is why they are not cached by default. If you enable Verify caching, be aware of any side effects that would normally occur in your ESM(s).

Similarly, if your ESM has side effects for resource access control that are useful to you, such as usage counts, be aware you'll lose these if you enable caching.

Parent topic: What is Cached?


Using Flush on Change

One configuration setting, flush on change, may be useful for organizations that only care about user-account locking. Many ESMs will lock a user account after a certain number of failed attempts to sign on. If a user does sign on successfully after a failed attempt (but not so many attempts that the account is locked), then the count of failed attempts is reset to zero. For this to work with caching, the ESM must see the successful Verify request, which means it must not be retrieved from the cache.

The "flush on change" setting tells ESF to discard a cached Verify request if it sees a Verify request with a different result for the same user. For example, assuming Verify caching and flush-on-change are enabled:

  • Bob signs on to his account. The request is sent to the ESM, and the result is cached.
  • Bob signs off, then signs on again. The cache is used to validate this attempt.
  • Bob signs off, then tries to sign on again, but mistypes his password. This doesn't match the cached request, so it's sent to the ESM. The ESM returns a "denied" result, and sets Bob's failed sign-on attempt count to 1.
  • The flush-on-change setting sees this is a Verify request for Bob, but with a different result, so it removes the old successful Verify entry from the cache.
  • Bob tries again, and types his password correctly this time. Since his previous attempt flushed his successful Verify from the cache, this request also goes to the ESM. The ESM returns an "allow" result and sets his failed count back to 0.

If flush-on-change had not been enabled, the final successful Verify would have been processed using the cache, and Bob's failed-attempt count would still be 1. If Bob repeated this pattern a few times, he'd be locked out, even though he'd signed on successfully between each failed attempt.

Parent topic: What is Cached?
Related concepts
Flush on Change


Enabling and Configuring Caching

There are two main parameters for enabling caching. They can be found on the ESF configuration pages in the Micro Focus Enterprise Server Administration user interface: the Default ES Security and MFDS Security tabs in the Security section, and the Security tab for each individual server (which overrides the Default ES Security settings). The two parameters are:

Cache TTL
This determines how long, in seconds, a cache entry will be kept. When a cache entry grows older than this time, it is ignored (and removed from the cache when space is needed for a new entry). This setting can be used to ensure that any out-of-date result can only last for the given amount of time, and that old results are discarded to make way for new ones.
Cache limit
This is the approximate size, in KB, of the cache (for each process). In the current implementation, the cache holds a bit more than 4 entries per KB; a 4 KB cache holds 18 entries, and you would need a 24 KB cache for 100 entries.

The best values for these parameters depend on your particular application mix. If your applications use many different MSS resources, they may benefit more from a larger cache, but larger caches also take longer to search.

A 16 KB cache limit and 60-second TTL are generally a good starting point.

  • Advanced Configuration
  • Requests
  • Flush on Change
  • Report Interval
  • Example
Parent topic: ESF Caching


Advanced Configuration

Some additional caching parameters can be controlled with settings in the "Configuration Text" area of the security configuration tab. All of these are entered in the optional [Cache] section.

Parent topic: Enabling and Configuring Caching


Requests

The requests setting specifies what types of ESF requests can be cached. It is set to a list of tokens, separated by commas or spaces. The possible tokens are:

auth-allow
Cache Auth requests that result in access allowed
auth-deny
Cache Auth requests that result in access denied
auth-unknown
Cache Auth requests for resources that are not known to the ESM(s)
auth
Same as "auth-allow auth-deny"
verify-allow
Cache Verify requests that result in sign-on allowed
verify-deny
Cache Verify requests that result in sign-on denied
verify
Same as "verify-allow verify-deny"
xauth-allow
Cache XAuth requests that result in access allowed
xauth-deny
Cache XAuth requests that result in access denied
xauth-unknown
Cache XAuth requests for resources that are not known to the ESM(s)
xauth
Same as "xauth-allow xauth-deny"

The default is requests=auth xauth.

Parent topic: Enabling and Configuring Caching


Flush on Change

Set flush on change to yes or 1 to tell the cache that it should discard any cached Verify result if it sees another request for the same user with a different result. See Using Flush on Change for more information. This is only useful when Verify caching is enabled.

Parent topic: Enabling and Configuring Caching
Related concepts
Using Flush on Change


Report Interval

Periodically, processes that use ESF will report some statistics about the cache, such as how many entries are in use and what percentage of requests are fulfilled using the cache (the cache "utilization" or "hit rate"). The information is reported as an ESF message, so it will appear in the console log (for CAS processes) or the MFDS journal. By default, this happens about every hour, though processes will only report it when an ESF request is made, so idle processes (for example, SEPs that are never used) won't report.

You can configure how often this reporting happens by setting the report interval option. Its value is an integer, representing the approximate time between reports in seconds. Setting this to 0 disables reporting.

Parent topic: Enabling and Configuring Caching


Example

[Cache]
 # Enable Verify caching, as well as Auth and XAuth, including the result of
 # requests for unknown resources
 requests=verify, auth, xauth, auth-unknown, xauth-unknown
 # Discard Verify result when a different request for the same user is processed
 flush on change=yes
 # Report cache statistics about every half-hour (1800 seconds)
 report interval=1800
Parent topic: Enabling and Configuring Caching


External Administrative Update Notification

ESF uses external security managers to make security decisions. Because those managers are not part of ESF, administrative changes to security information - changes to the security information for users, groups, or resources - are often made directly to the managers without any interaction with ESF. In some cases, it's necessary to notify ESF of these changes, so it (and its ESM Modules) can flush any cached results and update any internal information regarding the updated entity.

The ESF Administrative Update Notification request is part of the ESF API. It lets the calling environment notify ESF that one or more administrative changes have been made in an external security manager, so it should update any internal information that may be affected.

  • Using Update Notification Requests
  • Making an Update Notification Request
  • Handling Update Notifications in an ESM Module
Parent topic: Using External Security Facility (ESF) Features


Using Update Notification Requests

Administrative updates could include deleting a user, changing membership in a group, updating the access controls for a resource, and so on.

Enterprise Server components that use ESF provide various ways for an administrator to trigger an Administrative Update Notification request to ESF. After making security changes, you may need to tell MFDS and/or one or more Enterprise Servers to notify ESF, so that running systems pick up the security changes. This might be done through a GUI or with a command-line client; see the Enterprise Server administration documentation for details.

The Enterprise Server component will then make an Administrative Update Notification request to its ESF subsystem. ESF will flush any related cached results, and notify the affected ESM Module to do the same.

In environments where multiple processes use ESF and communicate through shared memory, such as ES/MTO, one process will handle each Update request. That process will flush any affected data from shared memory. However, each individual process will also need to be notified of the update before they handle any other ESF requests, in case those processes have cached security information in private memory.

So each time CAS SEPs make an ESF call, they check to see if any updates have been processed by other SEPs. If so, they will flush any relevant process-private data, and call the affected ESM Modules to instruct them to do the same.

These "pending update" operations come in two types. If only one update has been processed since the last time ESF was called, ESF will flush any data affected by that single update. However, if multiple updates have been processed, ESF flushes all cached information (also called a "refresh"). This avoids having to save an unbounded number of old update requests for processes that are rarely activated.

Parent topic: External Administrative Update Notification


Making an Update Notification Request

Administrative Update Notification uses the UPDATE form of the ESF API.

The Update Notification request has only one required parameter, a pointer to a valid ACEE (returned by an VERIFY request). Note that this means that Update Notifications require a valid set of user credentials. This allows Update Notifications to be audited with user information, and in the future may be used to restrict access to the Update Notification feature.

The Update Notification request can contain additional information that describes what was updated. Setting this information may reduce the amount of cached information that ESF and the ESM Modules have to discard, or the additional work needed to be done by the ESM Modules to update other internal state (such as information about group membership).

Not setting this additional information has some performance cost, but will probably only be noticeable under relatively heavy loads.

The optional fields include:

  • safpb_update::safpb_update_ENTITY_len and safpb_update::safpb_update_ENTITY_ptr: These fields can be set to indicate what entity (user, group, or resource) was affected by the change.
  • safpb_update::safpb_update_ACTION: This field can be set to indicate what action was performed: adding, changing, or removing an entity in the external security manager. The default (0) is other, which ESF treats as a generic request to flush information about the entity.
  • Safpb_Parameter_Block::safpb_type (note this is a field in the ESF parameter block itself, not in the Update structure): This field can be set to indicate what type of entity is affected. Possible values are:
    • saf78_TYPE_UPDATE_USER: A user definition was updated. Set safpb_update::safpb_update_ENTITY_ptr to point to a string with the username, and safpb_update::safpb_update_ENTITY_len to the length of the username.
    • saf78_TYPE_UPDATE_GROUP: A group definition was updated. Use safpb_update::safpb_update_ENTITY_ptr and safpb_update::safpb_update_ENTITY_len for the group name.
    • saf78_TYPE_UPDATE_RESOURCE: A resource access control definition was updated. Use safpb_update::safpb_update_ENTITY_ptr and safpb_update::safpb_update_ENTITY_len for the resource name.
    • saf78_TYPE_UPDATE_USERS: Multiple users were updated. ESF will flush all user-related information; safpb_update::safpb_update_ENTITY_ptr is not used.
    • saf78_TYPE_UPDATE_GROUPS: Multiple groups were updated. ESF will flush all group-related information; safpb_update::safpb_update_ENTITY_ptr is not used.
    • saf78_TYPE_UPDATE_RESOURCES: Multiple resources were updated. ESF will flush all resource-related information; safpb_update::safpb_update_ENTITY_ptr is not used.
    • saf78_TYPE_UPDATE_ALL (default): ESF will flush all cached information.

Note that if a user's primary group is changed, that will generally be a user update. Supplementary group membership may be stored as part of a user's definition or as part of a group's definition, depending on the ESM. For the MLDAP ESM Module, changes to a user's supplementary group information should be signalled with a saf78_TYPE_UPDATE_GROUP Update request.

You can also set the ESM Index in the request block to a non-zero value to indicate that the specified ESM Module is the one to receive the update notification. (ESM Modules are numbered consecutively from 1, in the order that they're shown in the security configuration in MFDS.) Unless performance becomes an issue, however, we recommend leaving this set to 0 and letting all ESM Modules be notified, to avoid errors that could leave an ESM Module with stale data.

Parent topic: External Administrative Update Notification


Handling Update Notifications in an ESM Module

ESF uses the optional ESM Update callback to notify ESM Modules of Update Notification requests. ESM Modules need to support this callback if they want to be informed of updates. See the ESF ESM Module Interface for more information.

Parent topic: External Administrative Update Notification


ESF Passtokens

Passtokens are an optional ESF feature for communicating a user's identity between security domains. Passtokens let one Enterprise Server component (an Enterprise Server region or MFDS) sign on to another Enterprise Server component on behalf of a user, without requiring that user's normal credentials (typically a password).

In effect, a passtoken is a one-time or limited-time substitute for a user's password. A passtoken is associated with a user (and signon group) when it is created, and can only be used to sign on as that user.

If passtokens are enabled, they may be used for these purposes:

  • Administrator convenience. When an administrator is signed on to either the MFDS administrative user interface or ESMAC, and switches to the other, the component that the administrator is coming from will send a passtoken to the component the administrator is going to. If the destination accepts the passtoken and the administrator has authority there, no manual signon will be necessary and the administrator can switch seamlessly between the two interfaces.
  • Inter-system communication. Some MTO facilities allow users with the appropriate rights to invoke functions or programs in other regions. In some cases these facilities can use passtokens rather than actual passwords, to avoid insecure storage and transmission of passwords.

Not all ESM Modules support passtokens. If you are using a module that does not do so to verify users, user identities will not be automatically transferred across security domains, and users will have to explicitly sign on with their normal credentials in each domain.

  • Access to Passtokens
  • Passtoken Design Considerations
  • Using Passtokens
  • Passtoken API
Parent topic: Using External Security Facility (ESF) Features


Access to Passtokens

Because passtokens bypass the normal security mechanism that establishes a user's identity, they can pose a security risk if an unprivileged user is allowed to create passtokens for other users.

Consequently, ESF Manager can be configured to disallow the generation or use of passtokens, or both; this affects any security domain (Enterprise Server server/ region, or MFDS) using that security configuration. Also, ESM Modules that implement passtokens will often provide additional controls. For example, the MLDAP ESM Module lets you specify for each user whether that user can generate passtokens for itself, for any user, or not at all; and whether that user can be signed on using a passtoken.

  • Passtoken Options for ESF Manager
  • Passtoken Options for the MLDAP ESM Module
  • Typical Passtoken Configurations
Parent topic: ESF Passtokens
Related concepts
MLDAP ESM Module


Passtoken Options for ESF Manager

Passtoken options for ESF Manager are currently set by editing the text in the Configuration Information area on the "Security" tab in the region configuration in MFDS (or the "Default ES Security" or "MF Directory Server" tabs in the security options in MFDS).

Note: This is not the configuration area in the Security Manager configuration, which is used to set security options for an ESM Module. It is the configuration area on the page where you set the list of security managers to use for a region, default security, or MFDS. Text in this area is organized into sections which begin with a "tag" in square brackets, followed by lines in the form of name=value.

You can restrict the use of passtokens in any Enterprise Server component that uses a particular Security Manager configuration by setting the following in that area:

[Passtoken]
allow=option

where option is one of none (disable passtokens), generate (allow passtoken generation but not use), signon (allow passtoken use for signon but not generation), both (allow both generation and signon), or yes (synonym for both).

Allowing only generation may be useful for a region that makes ISC requests to another region but does not receive them, and conversely allowing only signon may be useful for a region that receives remote requests but never makes them.

Parent topic: Access to Passtokens


Passtoken Options for the MLDAP ESM Module

The MLDAP ESM Module lets you specify passtoken-related rights for each user, by setting attributes in the user objects in the LDAP repository. It also provides some configuration options for its passtoken implementation.

  • ESM Module Configuration
  • LDAP Attributes
Parent topic: Access to Passtokens
Related concepts
MLDAP ESM Module


ESM Module Configuration

The ESM Module can be configured in MFDS; see MLDAP ESM Module configuration for more information. You can set values in the optional [Passtoken] section of the "Custom Configuration" area to set some options for passtoken processing.

In that section, there are two settings you can use to change the secret key for the MAC verifier used in the passtokens the MLDAP ESM Module generates. You can set the key directly in the MFDS configuration with the Secret keyword, or point the ESM Module to a file containing the secret key with the SecretFile keywords.

Note that passtokens generated by the MLDAP ESM Module in one security domain will only be verifiable by another instance of the module in another domain if both are configured with the same secret key.

You can also use the Duration keyword in that section to control how long passtokens remain valid after they are generated. (The default is one minute.) This should be long enough for the sending component to get the token to the receiving component, taking network delays into account, and for the receiving component to perform its Verify request; but making it too long gives an attacker more time to capture and replay a token, especially if it is being sent over an unsecured channel.

See MLDAP ESM Module Custom Configuration Information for more information.

Parent topic: Passtoken Options for the MLDAP ESM Module
Related concepts
Module Configuration
MLDAP ESM Module Custom Configuration Information


LDAP Attributes

There are two attributes of the LDAP microfocus-MFDS-User class which control access to passtokens:

microfocus-MFDS-User-CreateToken
This controls the user's ability to create passtokens. It can have the following values:
  • self: The user can create normal passtokens (good only for that user).
  • any: The user can create surrogate passtokens for other users.
  • Any other value (and the default): The user cannot create passtokens.
microfocus-MFDS-User-UseToken
This allows a user to be signed on using a passtoken. It can have the following values:
  • self: The user can be signed in with a normal passtoken, but not a surrogate passtoken.
  • any: The user can be signed in with a normal or surrogate passtoken.
  • Any other value (and the default): The user cannot be signed in using a passtoken.
Parent topic: Passtoken Options for the MLDAP ESM Module


Typical Passtoken Configurations

The appropriate passtoken configuration depends on the needs of your installation, its security requirements, and administrator convenience. Here are some example passtoken configurations for typical installations.

No Passtokens

The most secure option is to disable passtokens entirely. That means users will always have to sign on explicitly when entering security domains. Administrators will have to log on to MFDS and ESMAC separately, and user identity will not be automatically transferred over Inter-System Communication (ISC) links between ES regions, for purposes such as CICS Transaction Routing.

However, there is no danger of passtokens being abused in this configuration.

Disable passtokens in the ESF Manager configuration in each "Security Manager" object in the MFDS repository, using the MFDS administration GUI. See Passtoken Options for ESF Manager.

Passtokens for MFDS and ESMAC

Many administrators will find it convenient to enable passtokens for the MFDS and ESMAC administrative interfaces, especially since those two facilities provide links to each other, which makes it easy to switch between them. Because ESMAC runs as part of CAS within an Enterprise Server region, but MFDS is separate from any Enterprise Server region, they are in different security domains, despite those links; so without passtokens, the administrator has to log into each separately. With passtokens, an administrator can connect to MFDS or ESMAC, log in once, and then go between the two without losing access or having to log in again.

MFDS and ESMAC always use normal passtokens, so this feature can be enabled without enabling the more powerful (and riskier) surrogate tokens.

To enable passtokens for MFDS and ESMAC, do not disable passtoken support in your ESF Manager configuration (the "Custom Configuration" section of the "Security Manager") for MFDS or any ES region where you want this facility. Passtoken support is enabled in ESF Manager by default.

To use passtokens with MFDS and ESMAC, MFDS and the ES region you are administering must use the same security configuration. For example, you can set them both to use the Default ES Security configuration.

You might have to perform ESM-specific actions to enable normal passtoken generation and signon for your administrative users. With the MLDAP ESM Module, for each administrative user who should be able to switch between ESMAC and MFDS transparently, set the following attributes in the LDAP repository:

  • microfocus-MFDS-User-CreateToken to self
  • microfocus-MFDS-User-UseToken to self
Note: You do not need to do this for system users (such as SYSAD) unless you use them as administrator IDs. You only need to do it for user accounts with which your administrators actually sign into MFDS or ESMAC.

In its default configuration, MFDS does not require you to sign in. If you are not signed in, no passtoken will be generated when you switch to ESMAC. To use passtokens between MFDS and ESMAC, make sure you configure MFDS to require an administrative signon.

Passtokens for ISC

Customers who use the MTO Inter-System Communication (ISC) facility for CICS features such as Transaction Routing and Function Shipping between two Enterprise Server regions may want to enable passtokens for that purpose. That lets the two CICS regions apply the same security context to all the operations performed by an application, even when they cross security domains.

Note that passtokens are not supported for ISC conversations with non-Enterprise Server regions, such as MFE or mainframe CICS.

ISC passtokens are surrogate passtokens generated automatically by the system as necessary. They are always generated by the region's system user, which is the user account used to start the region.

To enable ISC passtokens, do not disable passtoken support in your ESF Manager configuration (the "Custom Configuration" section of the "Security Manager") for MFDS or any Enterprise Server region where you want this facility. Passtoken support is enabled in ESF Manager by default.

Also, you may have to perform ESM-specific actions to enable:

  • Surrogate passtoken generation by any user account used to start a region that will be making ISC requests to another Enterprise Server region
  • Surrogate passtoken signon for any user account that will run a transaction that will cause an ISC request (for example, by starting a transaction in another region)

For the MLDAP ESM Module, that entails:

  • For all user accounts used to start the region, set the LDAP user attribute microfocus-MFDS-User-CreateToken to any
  • For all user accounts that will run CICS transactions that may cause an ISC request, set the LDAP user attribute microfocus-MFDS-User-UseToken to any

If the regions use different LDAP repositories, note that the system user account (the one generating the token) belongs to the region that initiates the request, and the regular user account (which is signed on using the token) belongs to the region that processes the request.

Parent topic: Access to Passtokens
Related concepts
Passtoken Options for ESF Manager


Passtoken Design Considerations

When designing passtokens, you need to take into account both functional and design considerations.

Functional Requirements

  • Allow a verified user in one security domain to perform an automatic signon in another domain. That signon can fail if the target domain refuses to verify the user.
  • Avoid creating a security hole that would allow users to bypass the normal signon mechanism.

Design Considerations

  • The passtoken contents and passtoken processing (generation and verification) is left to the ESM Module (and its associated ESM) that generates and consumes a given passtoken.
  • Passtoken operations fail gracefully if they are disabled, or an ESM Module used by one of the security domains does not support passtokens.
  • Passtokens should be hard to forge or replay.
  • It should be difficult or impossible to derive sensitive information (such as passwords) from passtokens. This requirement is flexible, if passtokens themselves are mostly exposed only on the wire, because it's likely that users will either be using SSL or exposing passwords on the wire, which is a greater security risk.
  • A given passtoken is specific to a user and signon group.
  • Passtokens should be single-use or short-lived. The mechanism for achieving that is left to the ESM Module.
Parent topic: ESF Passtokens


Using Passtokens

In this version of ESF, there are no facilities for manually using or administering passtokens, aside from the access controls described above. Passtokens are used automatically by certain Enterprise Server facilities where appropriate.

Customers interested in using passtokens in their own applications should contact Micro Focus to discuss possible product enhancements and early-adopter programs.

Parent topic: ESF Passtokens
Related concepts
Access to Passtokens


Passtoken API

The passtoken API is not documented for customer use in this release. Customers interested in using passtokens in their own applications should contact Micro Focus to discuss possible product enhancements and early-adopter programs.

Parent topic: ESF Passtokens


Security Federation

ESF lets you configure more than one External Security Manager (ESM). There are various reasons for using multiple ESMs. Some organizations use one ESM to authenticate users (for example, if your Enterprise Server users are also operating system users), and another to handle resource access. Others might use one ESM to perform the initial stage of user authentication, and a second one to make additional checks (for example, to restrict which OS users can sign in to ES/MSS facilities). And in other cases, user, group, and resource definitions might simply be split among ESMs for administrative reasons.

In some cases, you want ESF to treat multiple ESMs as if they were a single security manager, at least for some purposes. This is called federation. ESF 1.14 and later has an option to enable a degree of federation, for ESM Modules that support it.

You configure federation for all of ESF (in the security configuration for an Enterprise Server or MFDS), but it's actually implemented by individual ESM Modules. Each module takes different actions depending on the federation setting.

Currently only the MLDAP ESM Module has special processing for federation, and it only applies if you have multiple LDAP ESMs in the stack. Federation currently has no effect if you have no more than one instance of the MLDAP ESM Module in your configuration.

  • What Federation Does
  • Configuring Federation
Parent topic: Using External Security Facility (ESF) Features
Related concepts
MLDAP ESM Module
Federation in the MLDAP ESM Module


What Federation Does

When federation is enabled, ESM Modules attempt to share information and responsibilities, so that multiple ESMs behave as if they all had the same information about users, groups, and resources. For example, suppose you have multiple LDAP repositories with security information: a user might be defined in one LDAP repository, and a resource access control rule in another. If you want the resource control rules from one LDAP repository to apply to users defined in another LDAP repository, you would enable federation.

Disabling federation, on the other hand, tells ESM Modules to attempt to act independently of each other. With federation disabled, the access control rules defined in one ESM should only apply to users who are also defined in that ESM.

There is also a "compatibility" federation setting, which maintains the behavior of ESF 1.13 and earlier. If compatibility federation mode is set, ESM Modules may have some interaction, possibly leading to unexpected results in some cases. This is the default, to avoid introducing incompatible behavior in existing installations. However, if you have multiple ESMs configured ("stacked"), you should probably explicitly enable or disable federation.

If you are not sure what setting to use, try the following guidelines:

  • If your configuration only has one ESM, you don't need to worry about configuring federation.
  • If your configuration has multiple ESMs, but you aren't using the MLDAP ESM Module, or you only have one instance of the MLDAP ESM Module, you don't need to configure federation. You might want to, though, in case it becomes relevant in a later release.
  • Do you define users in one ESM, and the groups they belong to in another? If so, you should enable federation (you expect your security information to be combined).
  • Do you define users and/or groups in one ESM, and resource access rules that apply to them in another? If so, you should enable federation.
  • Are the resource access rules defined in each ESM meant only to apply to users and groups known to that ESM? If so, you should disable federation (you expect your ESMs to act independently).

If none of the above apply, you can probably disable federation.

Parent topic: Security Federation


Configuring Federation

Federation is configured using the configuration text area of the relevant Security Configuration page in the MFDS administration user interface. This is the security configuration tab for an individual server, or the "Default ES Security" page in the global security settings, or the "MFDS Security" page.

Note: It is not the Security Manager Configuration page, where you specify the ESM Module name.

To configure federation, add the following section:

[Operation]
Federate=setting

where setting is yes, no, or compatible. The default is compatible, which preserves the behavior of ESF 1.13 or older.

Parent topic: Security Federation


ESF Manager Messages and Logging

ESF Manager generates various log messages regarding errors, warnings, and successful completion of infrequent activities (such as loading and initializing an ESM Module). These messages are sent to an environment-specific logging facility, such as the CAS Console Log and the MFDS Journal. (See saf-env.c for more information on ESF Manager environments.)

Each ESF log message has:

  • A number. Each of the different messages is assigned an integer number in the range 0-8999; messages 9000-9999 are reserved for customer use. Message numbers are more or less grouped by ESF Manager component:
    Manager Interface | Messages 0-99
    ESF API Processing | Messages 100-199
    ESM Module Interface | Messages 200-299
    Environment Support | Messages 300-399
    Cache | Messages 400-499
    User Exit Processing | Messages 500-599
    Auditing | Messages 600-699
    ESM Modules | Messages 1000-1999
    Temporary | Messages 2000-2999
  • A level: informational, warning, error, or critical (fatal error), indicated by the letters "I", "W", "E", and "C".
  • Message text. ESF Manager message text is retrieved from a message catalog for internationalization purposes; if a catalog for the current language is not available, a default English message is used.
  • For some messages, substitution parameters are replaced with event- specific details.
  • Manager Interface Messages
  • ESF API Processing Messages
  • ESM Module Interface Messages
  • Processing Environment Messages
  • Cache Messages
  • User Exit Messages
  • Auditing Messages
  • ESM Module Messages
  • Temporary Messages
Parent topic: Using External Security Facility (ESF) Features


Manager Interface Messages

Currently no messages in this class have been defined.

Parent topic: ESF Manager Messages and Logging


ESF API Processing Messages

  • 103W Admin "type" request failed: "value"
    An ESF Admin request of the given type failed, returning error code value.
  • 104W Update ("type") request failed: "value"
    An ESF Update request of the given type failed, returning error code value.
  • 105W ESM Module number ("name") returned error code value ("description") from Update (type)
    The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Update operation for a cached update.
  • 110E ESM Module number ("name") returned error code value ("description") from Verify
    The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from a Verify (authenticate user) operation. This constitutes a Fail result for the Verify request.
  • 111E ESM Module number ("name") returned error code value ("description") from Auth
    The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Auth (authorize resource access) operation.
  • 112E ESM Module number ("name") returned error code value ("description") from XAuth
    The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Xauth (authorize resource access) operation.
  • 113E ESM Module number ("name") returned error code value ("description") from Admin
    The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Admin (administrative action) operation.
  • 114E ESM Module number ("name") returned error code value ("description") from Update
    The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Update (update notification) operation.
Parent topic: ESF Manager Messages and Logging


103W Admin "type" request failed: "value"

An ESF Admin request of the given type failed, returning error code value.
Parent topic: ESF API Processing Messages


104W Update ("type") request failed: "value"

An ESF Update request of the given type failed, returning error code value.
Parent topic: ESF API Processing Messages


105W ESM Module number ("name") returned error code value ("description") from Update (type)

The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Update operation for a cached update.
The type is either "single update" or "refresh all", indicating whether the ESM Module was asked to refresh its private data associated with one update, or clear all of its privately cached security information. See External Administrative Update Notification for more information.
Parent topic: ESF API Processing Messages
Related concepts
External Administrative Update Notification


110E ESM Module number ("name") returned error code value ("description") from Verify

The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from a Verify (authenticate user) operation. This constitutes a Fail result for the Verify request.
Parent topic: ESF API Processing Messages


111E ESM Module number ("name") returned error code value ("description") from Auth

The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Auth (authorize resource access) operation.
Parent topic: ESF API Processing Messages


112E ESM Module number ("name") returned error code value ("description") from XAuth

The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Xauth (authorize resource access) operation.
Parent topic: ESF API Processing Messages


113E ESM Module number ("name") returned error code value ("description") from Admin

The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Admin (administrative action) operation.
Parent topic: ESF API Processing Messages


114E ESM Module number ("name") returned error code value ("description") from Update

The ESM Module name (at position number in the stack, if multiple modules are configured) returned error code value from an Update (update notification) operation.
Parent topic: ESF API Processing Messages


ESM Module Interface Messages

  • 200I Loaded ESM Module "name"
    The binary file name has been loaded as an ESM Module and initialized.
  • 201C Unable to load ESM Module "name": reason
    The ESM Module in the binary file name could not be loaded; reason is a numeric reason code.
  • 202C ESM Module "name" returned invalid procedure table
    The ESM Module name returned an invalid result when its initial entry point was called.
  • 203C ESM Module "name" initialization failed
    The ESM Module name returned an error from its initialization procedure.
  • 204W ESM Module index returned error code value from Exit
    The ESM Module (indicated by its position in the ESM Module list, index) returned a non-zero value from its exit procedure.
Parent topic: ESF Manager Messages and Logging


200I Loaded ESM Module "name"

The binary file name has been loaded as an ESM Module and initialized.
Parent topic: ESM Module Interface Messages


201C Unable to load ESM Module "name": reason

The ESM Module in the binary file name could not be loaded; reason is a numeric reason code.
Parent topic: ESM Module Interface Messages


202C ESM Module "name" returned invalid procedure table

The ESM Module name returned an invalid result when its initial entry point was called.

Parent topic: ESM Module Interface Messages


203C ESM Module "name" initialization failed

The ESM Module name returned an error from its initialization procedure.

Parent topic: ESM Module Interface Messages


204W ESM Module index returned error code value from Exit

The ESM Module (indicated by its position in the ESM Module list, index) returned a non-zero value from its Exit procedure.

Parent topic: ESM Module Interface Messages


Processing Environment Messages

  • 301W Unable to open log file "name": ("value") description
    ESF was unable to open the log file "name". The value is the error code and description is a short description. (The file is specified by the MF_SAFLOG environment variable. This function only applies to standalone utilities that use ESF, and not to main Enterprise Server components.)
  • 320C CAS support function "name" is not available
    The required CAS support function name is not available to ESF Manager, possibly due to a version mismatch between modules or a resource constraint. This is a fatal error.
  • 321E Unable to allocate ACEE (error code)
    ESF Manager was unable to allocate an ACEE structure, which is required for user verification. code is the error returned by the environment's ACEE allocation function.
  • 322E Unable to allocate named shared memory (error code)
    ESF Manager was unable to allocate a named shared memory area, either for its own use or to satisfy a request from an ESM Module. code is the error returned by the environment's shared-memory allocation function.
Parent topic: ESF Manager Messages and Logging


301W Unable to open log file "name": ("value") description

ESF was unable to open the log file "name". The value is the error code and description is a short description. (The file is specified by the MF_SAFLOG environment variable. This function only applies to standalone utilities that use ESF, and not to main Enterprise Server components.)
Parent topic: Processing Environment Messages


320C CAS support function "name" is not available

The required CAS support function name is not available to ESF Manager, possibly due to a version mismatch between modules or a resource constraint. This is a fatal error.
Parent topic: Processing Environment Messages


321E Unable to allocate ACEE (error code)

ESF Manager was unable to allocate an ACEE structure, which is required for user verification. code is the error returned by the environment's ACEE allocation function.
Parent topic: Processing Environment Messages


322E Unable to allocate named shared memory (error code)

ESF Manager was unable to allocate a named shared memory area, either for its own use or to satisfy a request from an ESM Module. code is the error returned by the environment's shared-memory allocation function.
Parent topic: Processing Environment Messages


Cache Messages

Currently no messages in this class have been defined.

Parent topic: ESF Manager Messages and Logging


User Exit Messages

Currently no messages in this class have been defined.

Parent topic: ESF Manager Messages and Logging


Auditing Messages

  • 601C Auditing subsystem startup failed: ("value") description
    ESF was unable to connect to the auditing subsystem. This is a critical failure (if auditing is enabled). value is the return code from auditing startup and description is a short description of the problem.
  • 602C Auditing: cobaudit_event failed: ("value") description
    The auditing subsystem failed to audit a security event. This is a critical failure (if auditing is enabled). value is the return code from auditing startup and description is a short description of the problem.
Parent topic: ESF Manager Messages and Logging


601C Auditing subsystem startup failed: ("value") description

ESF was unable to connect to the auditing subsystem. This is a critical failure (if auditing is enabled). value is the return code from auditing startup and description is a short description of the problem.
Parent topic: Auditing Messages


602C Auditing: cobaudit_event failed: ("value") description

The auditing subsystem failed to audit a security event. This is a critical failure (if auditing is enabled). value is the return code from auditing startup and description is a short description of the problem.
Parent topic: Auditing Messages


ESM Module Messages

See the documentation for your MLDAP ESM Module for information on its log messages.

Parent topic: ESF Manager Messages and Logging
Related concepts
MLDAP ESM Module


Temporary Messages

These messages will not normally be logged by released products. They may appear in Early-Adopter releases. If you receive a message in this range, contact SupportLine for more information.

Parent topic: ESF Manager Messages and Logging


ESF User Exit

The ESF User Exit is a feature of the Enterprise Server External Security Facility (ESF). It lets custom actions be performed at certain points while processing security requests. The custom functionality is performed by a loadable module which may be provided by Micro Focus, a customer, or a third party. The User Exit may be used to modify or filter particular security requests, for example. A sample User Exit module, called the "Referential Integrity" exit, is included with Enterprise Developer and the source code is available upon request. The sample module must be enabled by the product administrator. By default no user exit module is enabled.

The user exit is available starting with ESF 2.1, released as part of Enterprise Developer 2.2 Update 2 Hotfix 7 and Enterprise Developer 2.3.

Currently the only exit point in ESF is prior to processing ESF Admin requests. ESF Admin is a mechanism for adding, removing, updating, and querying security objects (users, groups, and resource access control rules). See the documentation for the esfadmin command for more information. The Admin user exit point can be used to block particular admin requests or perform other actions based on them, as the Referential Integrity sample user exit module demonstrates.

More exit points may be added in future product releases. (New releases will remain backward-compatible with older exit modules.)

  • ESF User Exit File Names
    An ESF User Exit module file must follow certain rules for how it is built and named.
  • Enabling an ESF User Exit
  • Configuring an ESF User Exit
Parent topic: Using External Security Facility (ESF) Features


ESF User Exit File Names

ESF User Exit modules, like ESM Modules, are loaded at run time by ESF. In order for ESF to locate and load the correct type of module, and use it successfully, certain rules must be followed. These rules depend on the operating system where Enterprise Server is running.

By default ESF looks for exit modules in specific directories in the product installation area. For Windows, it looks in the bin and bin64 directories, for 32- and 64-bit processes respectively. For UNIX / Linux, it looks in the lib directory. You can load the exit module from a different directory using ESF configuration options, as described in To enable the ESF user exit through configuration.

ESF User Exit module files have a base name, which is the part of the filename that identifies the module file. The base name is followed by a suffix which includes the file extension (.DLL or .so, and on UNIX/Linux platforms may include other characters either before or in the extension.

  • For Windows platforms, your module must be a 32-bit DLL. The module base name will be the filename up to the .DLL extension. For example, the sample Referential Integrity module is supplied as saf_refint_exit.dll, so its base name is saf_refint_exit.
    • For 64-bit Windows, if you will be using the exit with 64-bit Enterprise Servers, you will also need a 64-bit version of the DLL.
  • For UNIX and Linux platforms, your module must be a shared object. It must be built for thread-safe execution (for example using the cob -t command). You can create single-threaded and multi-threaded versions of the module, but we recommend avoiding the use of separate threads in the module. For MFDS and 32-bit Enterprise Server instances, you need a 32-bit version of the module; if you are running any 64-bit Enterprise Server instances, you will need a 64-bit version. The module's base name will be followed by a suffix which varies by platform, bitness, and threading mode.
    • For 64-bit modules, the suffix begins with 64.
    • For thread-safe modules, the suffix continues with _t. If your module only comes in a thread-safe version (recommended), you can copy it or create links under both suffixes (with _t and without it).
    • The suffix then continues with the extension. On HP-UX, this is .sl; on all other platforms it is .so.

For example, suppose that you have created an ESF User Exit module and chosen the base name my_exit for it.

On Windows, you would have a 32-bit version of this module named my_exit.dll, and optionally a 64-bit version also named my_exit.dll. Since they have the same name, they would have to be located in different directories, usually the product's bin and bin64 directories.

On UNIX, you would normally create four versions of your exit module and put them in the product's lib directory:
my_exit.so | Single-threaded, 32-bit
my_exit_t.so | Thread-safe, 32-bit
my_exit64.so | Single-threaded, 64-bit
my_exit64_t.so | Thread-safe, 64-bit
The single-threaded versions can be thread-safe, as long as they do not create threads, so often my_exit.so and my_exit_t.so will be the same file, and similarly for my_exit64.so and my_exit64_t.so.
Parent topic: ESF User Exit
Related tasks
To enable a mandatory ESF User Exit
To enable the ESF user exit through configuration
Related information
Enabling an ESF User Exit


Enabling an ESF User Exit

You can enable an ESF user exit in one of the following ways:

  • In the text in the Configuration Information area.
  • By placing a module in the product's bin (Windows) or $COBDIR/lib (UNIX) directory.

ESF configuration

You can configure ESF to load a user exit module by name. By default this module must be in the product's bin (or bin64 for 64-bit Windows processes) folder. this module must be in the product's $COBDIR/lib directory. You can also configure ESF to load the module from an arbitrary path.

Enabling the user exit through the configuration text has these advantages:

  • Using the exit is optional for the esfadmin utility and other processes that are not running under MFDS or an enterprise server region. This is only an advantage if the product administrator wants the use of the exit to be optional.
  • Different security configurations can use different exit modules (or no exits at all). This is useful, if you want an exit to be used only by production regions and not by development ones, for example.
  • The exit module can be located outside the product directory, which is usually a better choice when developing a new user exit module.

Using a default module filename

If there is a module named saf_exit*.{dll|so} (where * is the suffix) in the product's bin or bin64 $COBDIR/lib directory (see ESF User Exit File Names), that module will automatically be loaded as the user exit. For example, you can copy the sample user exit module saf_refint_exit*.{dll|so} to saf_exit*.{dll|so} (or create a link to it from that name) to make the Referential Integrity sample module the user exit for all processes.

Using a default exit filename has the following advantages:

  • The use of the exit is automatic and mandatory. This enables administrators to use the exit to enforce certain behavior.
  • It makes it easier to use the exit as no configuration settings are required in the security configurations in Micro Focus Enterprise Server Administration, and no configuration file is required for the esfadmin utility.
  • To enable the ESF user exit through configuration
  • To enable a mandatory ESF User Exit
Parent topic: ESF User Exit
Related information
ESF User Exit File Names


To enable the ESF user exit through configuration

Enterprise Developer or Enterprise Server must be installed. The Micro Focus Directory Server (MFDS) process must be running.

Ensure your exit module exists in the appropriate forms and has the correct filenames, as described in ESF User Exit File Names.

  1. Connect a browser to Micro Focus Enterprise Server Administration and navigate to the page for the security configuration you wish to modify. This can be:
    • The Security tab of an individual Enterprise Server configuration.
    • The Default ES Security tab in the Security section.
    • The MF Directory Server tab in the Security section.
    Note: Do not try to configure the user exit on a Security Manager page. Doing so will have no effect.
  2. In the Configuration Information text box, add the following lines:
    [Operation]
user exit=module base name

    The module base name value is the base name of your exit module, as defined in ESF User Exit File Names. It can be prefixed with the path to the module; if not, the module must be in the product's bin directory (32-bit Windows), bin64 directory (64-bit Windows processes), or lib directory (UNIX/Linux). The Operation and user exit keywords are case-insensitive; the filename is case-insensitive on Windows but case-sensitive on UNIX and Linux.

  3. Click OK or Apply to save your changes. The change takes effect when the region or MFDS process is restarted.
For the Referential Integrity sample exit:
# Enable the "Referential Integrity" user exit
[Operation]
user exit=saf_refint_exit

(The first line is a comment and can be omitted or changed.)

Restart affected regions and/or the MFDS process to have the change take effect. The region console logs should now contain messages indicating the exit module has been loaded and initialized.
Parent topic: Enabling an ESF User Exit
Related information
ESF User Exit File Names

Configuring a user exit for esfadmin

Enterprise Server includes a command line utility named esfadmin which can be used to perform ESF Admin tasks (adding, removing, modifying, and querying objects in the security data repository) from a command-line session or scripts. Unlike Enterprise Server regions and MFDS, esfadmin does not use a security configuration from Enterprise Server Administration, so you cannot configure an ESF user exit for it using the process described above. Instead you must provide it with a configuration file.

  1. Using a text editor, create a text file containing the user exit configuration (and optionally any other ESF configuration you need for esfadmin). For example, you might name the file esfadmin-config.txt and it could contain
    [Operation]
user exit=saf_refint_exit
  2. When you execute esfadmin, use the -c option to specify the name (and, if necessary, path) of your configuration file. For example: esfadmin -cesfadmin-config.txt addgroup group=DEVTEAM.


To enable a mandatory ESF User Exit

  1. Ensure your exit module exists in the appropriate forms and has the correct filenames, as described in ESF User Exit File Names.
  2. To force any process that uses ESF to use an ESF User Exit module, you need to place the module in the appropriate location with the proper name. If a module with this name exists, ESF will always use it and the configuration option for enabling the user exit will be ignored. The basename for the mandatory ESF User Exit module is saf_exit. For example, to make the referential integrity exit mandatory, do one of the following, depending on your operating system:
    • Windows:

      Copy your 32-bit module to bin/saf_exit.dll and your 64-bit module to bin64/saf_exit.dll under your product installation directory.

      cd C:\Program Files (x86)\Micro Focus\Enterprise Developer
copy bin\saf_refint_exit.dll bin\saf_exit.dll
copy bin64\saf_refint_exit.dll bin64\saf_exit.dll
    • UNIX:

      Copy your user exit modules to $COBDIR/lib, using the destination name saf_exit followed by the correct suffixes.

      cd $COBDIR/lib
cp saf_refint_exit.so saf_exit.so
cp saf_refint_exit_t.so saf_exit_t.so
cp saf_refint_exit64.so saf_exit64.so
cp saf_refint_exit64_t.so saf_exit64_t.so

    You can also use symbolic or hard links in place of the copy statements, as permitted by your file system.

  3. Restart MFDS and the enterprise server regions for the change to take effect. The region console logs should now contain messages indicating the exit module has been loaded and initialized.
Parent topic: Enabling an ESF User Exit
Related information
ESF User Exit File Names


Configuring an ESF User Exit

ESF User Exit modules often have configurable options, to alter their behavior, enable tracing messages, and so on.

The User Exit module has access to the configuration text area provided to ESF by the security configuration. That is the Configuration Information text area that appears on these three pages in Enterprise Server Administration:

  • The Security tab of an individual Enterprise Server configuration.
  • The Default ES Security tab in the Security section.
  • The MF Directory Server tab in the Security section.
Note: Do not try to configure the user exit on a Security Manager page. Doing so will have no effect.

In that Configuration Information text, you can add a section for use by the User Exit. By convention, the section name [user exit] is reserved for this purpose. (You can use any section name, but it's possible other names could conflict with sections defined by later releases of Enterprise Server.)

See Configuration options for the Referential Integrity User Exit for an example of a user exit configuration.

Configuring the User Exit for esfadmin

Since the esfadmin command-line utility does not use a security configuration defined in Enterprise Server Administration, if you need to supply user exit configuration parameters to it, you must use a text file and the -c command-line option. See To enable the ESF user exit through configuration for an example.

  • Configuration options for the Referential Integrity User Exit
    Describes the options that can be configured for the Referential Integrity sample ESF User Exit module.
Parent topic: ESF User Exit


Configuration options for the Referential Integrity User Exit

[user exit]
allow dangling ACE removal=boolean
allow multiple ACEs=boolean
allow redundant membership=boolean
deny if dangling references=boolean
tracing=trace-setting

The section name (user exit) and option names are case-insensitive. Options may appear in any order. Whitespace is ignored. Comments are prefixed with #.

A boolean value may be 0, no (or n), or false (or f) for false; or 1, y, yes, t, or true for true. The value is case-insensitive.

The trace-setting value syntax is described below.

See The Referential Integrity Sample User Exit for more information about the Referential Integrity User Exit module.

All of the configuration items are optional. The default value for Boolean options is false, and tracing is disabled by default.

allow dangling ACE removal

If this option is enabled, then if an administrator attempts to remove an Access Control Entry (ACE) from a resource access rule, and the ACE refers to a user or group that does not exist, the ACE is removed anyway. Under the default set of constraints this is not permitted.

allow multiple ACEs

If this option is enabled, an administrator will be allowed to add an ACE to a resource access rule even if that rule already contains an ACE for the same actor (user or group). This is technically unnecessary because all of the permissions for an actor can be expressed in a single ACE, but is sometimes convenient. Under the default set of constraints this is not permitted (only one ACE for an actor can be defined for a given rule).

allow redundant membership

If this option is enabled, an administrator will be allowed to add a user to a group even if that group is the user's default group. This has no effect on the user's group membership, unless the user's default group is later changed. Some administrators prefer to make users explicit members of their default group so that a listing of the group shows all its members. This redundant membership is not permitted under the default set of constraints.

deny if dangling references

Under normal processing, a user can be added even if some groups already list that user as a member, or if some resource rules contain ACEs that refer to that user. Similarly, a group can be added even if some users list that group as their default group. Normally the Referential Integrity exit would prevent such dangling references from being created in the first place, but they may occur due to administering the security repository data by other means, such as LDAP import operations. If enabled, this option activates additional constraints that prevent adding a user or group if there are references to it.

tracing

The trace-setting value can be a non-negative integer. 0 disables tracing and positive values enable it. In principle higher values enable more tracing messages but in the current version of the exit all messages are emitted at level 1. The keyword yes (or y) will also enable tracing, at the highest level. Any other value disables it.

Tracing takes the form of informational ESF messages, which will be written to the region console log (for ES regions), the journal (for MFDS), or standard error (esfadmin), just as other ESF messages are.

An example configuration:
# Configure the Referential Integrity user exit module
[user exit]
allow dangling ACE removal=true
allow multiple ACEs=false
allow redundant membership=y
deny if dangling references=yes
tracing=1
Parent topic: Configuring an ESF User Exit
Parent topic: The Referential Integrity Sample User Exit


The Referential Integrity Sample User Exit

Enterprise Server includes a sample ESF User Exit, the Referential Integrity User Exit (saf_refint_exit). It demonstrates the ESF User Exit feature and is fully supported by Micro Focus for development and production use.

The Referential Integrity exit module intercepts ESF Admin requests, which are made by Enterprise Server Administration and the esfadmin command line utility. It enforces certain rules or constraints on actions that change information in the security data repository: adding users, deleting groups, and so on. Constraints are enforced by denying requests that would violate the constraints, or in some cases by automatically making additional changes to keep the security data consistent.

Currently the Referential Integrity exit is only useful in a security configuration that includes an LDAP-based security manager, because the MLDAP ESM Module is the only ESM Module that supports ESF Admin requests.

  • Configuration options for the Referential Integrity User Exit
    Describes the options that can be configured for the Referential Integrity sample ESF User Exit module.
  • Source Code for the Sample User Exit
  • Rules Enforced by the Referential Integrity User Exit
Parent topic: Using External Security Facility (ESF) Features


Source Code for the Sample User Exit

Source for the "Referential Integrity" sample user exit module is not currently provided with the product. To obtain the source code for the sample, and the ESF SDK required to build it, contact your Micro Focus support representative.

Micro Focus supports the Referential Integrity sample as it is shipped with the product. Customer changes to the sample are supported only on an advice basis.

Parent topic: The Referential Integrity Sample User Exit


Rules Enforced by the Referential Integrity User Exit

These are the constraints (consistency rules) enforced by the Referential Integrity User Exit.

The constraints listed here are the default behavior of the exit module. The user exit configuration can relax some constraints or add others. See Configuration options for the Referential Integrity User Exit.

User Operations

  • Add user
    • Deny request if the user already exists
  • Delete user
    • Deny request if the user does not exist
    • Automatically remove the user from all groups
    • Automatically remove all resource Access Control Entries (ACEs) that refer to the user
      Note: ACEs with wildcard actors, such as allow:U*:read, are not automatically removed.

Group Operations

  • Add group
    • Deny request if the group already exists
  • Delete group
    • Deny request if the group does not exist
    • Deny request if any users still belong to the group
    • Automatically remove all resource ACEs that refer to the group
      Note: ACEs with wildcard actors are not automatically removed.
  • Add user to group
    • Deny request if the user or group does not exist
    • Deny request if the user already belongs to the group
  • Remove user from group
    • Deny request if the user or group does not exist
    • Deny request if the user is not a member of the group

Resource Access Rule Operations

  • Delete resource class
    • Deny request if the class contains any resource access rules
  • Add resource rule
    • Deny request if the rule already exists in the given class
  • Delete resource rule
    • Deny request if the rule does not exist
    • Deny request if the rule contains any ACEs
  • Add ACE to resource rule
    • Deny request if the rule or actor (user or group) does not exist
    • Deny request if the rule already contains an ACE for the given actor
  • Delete ACE from resource rule
    • Deny request if the rule or actor does not exist
    • Deny request if the ACE does not exist in the specified rule
Parent topic: The Referential Integrity Sample User Exit


Result Codes in the ESF API Parameter Block

Verify, Auth, XAuth, and Admin indicate that a request was granted, was denied, or could not be processed (and in some cases indicate additional information such as password expiration) by setting values in the ESF API parameter block.

Result codes go in three one-byte values in the RETCODES structure in the parameter block. There are three fields, labelled:

  • safpb_api_rc
  • safpb_mgr_return
  • safpb_mgr_reason

The safpb_api_rc codes depend on the function (Verify /Auth /XAuth) being invoked; the other two codes depend on the value of safpb_api_rc. Various valid combinations are listed in safapi.h.

  • Typical Result Codes for Verify
  • Typical Result Codes for Auth and XAuth
  • Typical Result Codes for Admin
Parent topic: Using External Security Facility (ESF) Features


Typical Result Codes for Verify

For a Verify request, the most common result code triplets are listed in the table below. These will generally be suitable for most ESM Modules. For an explanation of the response classes (Allow, Deny, Fail, and Unknown), see the section ESF API Calls.

rc | return | reason | Meaning
saf78_SAF_RC_SUCCESS (0) | saf78_RC_NORMAL (0) | saf78_RS_NORMAL (0) | Verification succeeded, no additional information (this is an Allow result)
saf78_SAF_RC_NOT_COMPLETE (4) | saf78_RC_NO_DECISION (0) | saf78_RS_ESM_NOT_CALLED (0) | The ESM Module does not implement this procedure, or it has decided that this request does not apply to it (this is an Unknown result)
saf78_SAF_RC_NOT_COMPLETE (4) | saf78_RC_NO_USER_PROFILE (4) | saf78_RS_NORMAL (0) | The ESM does not have a record for this user (this is an Unknown result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_NORMAL (0) | saf78_RS_NORMAL (0) | The ESM rejected this request, and does not wish to provide any additional information (note this is a Deny result, not a Fail result, despite the name of the associated constant). This code can be used if the organization's security policy requires not revealing information about why a signon request was denied.
saf78_SAF_RC_FAILURE (8) | saf78_RC_PWRD_INVALID (8) | saf78_RS_NORMAL (0) | Verification failed because the supplied password was incorrect (this is a Deny result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_PWRD_EXPIRED (12) | saf78_RS_NORMAL (0) | Verification failed because the supplied password has expired (this is a Deny result). Some ESM Modules will accept the request if it is repeated with a new password supplied in the optional new-password field.
saf78_SAF_RC_FAILURE (8) | saf78_RC_PWRD_CHANGE_ERR (16) | saf78_RS_NORMAL (0) | Verification failed because the supplied new password was not accepted by the ESM (this is a Deny result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_USER_REVOKED (28) | saf78_RS_NORMAL (0) | Verification failed because signon is disabled for the user's account (this is a Deny result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_DATABASE_ERROR (92) | saf78_RS_NORMAL (0) | Verification failed because the ESM Module or its associated ESM was unable to process the request (this is a Fail result)
Parent topic: Result Codes in the ESF API Parameter Block


Typical Result Codes for Auth and XAuth

For an Auth or XAuth request, the most common result code triplets are listed in the table below. These will generally be suitable for most ESM Modules. For an explanation of the response classes (Allow, Deny, Fail, and Unknown), see the section ESF API Calls.

rc | return | reason | Meaning
saf78_SAF_RC_SUCCESS (0) | saf78_RC_USER_IS_AUTH (0) | saf78_RS_NORMAL (0) | Authorization is granted, no additional information (this is an Allow result)
saf78_SAF_RC_SUCCESS (0) | saf78_RC_ACCESS_INFO (20) | saf78_RS_ACCESS_{NONE (0), READ (4), UPDATE (8), CONTROL (12), ALTER (16)} | (Auth only) The user has the specified level of access to the resource
saf78_SAF_RC_NOT_COMPLETE (4) | saf78_RC_NO_DECISION (0) | saf78_RS_ESM_NOT_CALLED (0) | The ESM Module does not implement this procedure, or it has decided that this request does not apply to it (this is an Unknown result)
saf78_SAF_RC_NOT_COMPLETE (4) | saf78_RC_RESOURCE_NOT_PROT (4) | saf78_RS_NO_RESOURCE_PROF (0) | The ESM does not have a record for this resource (this is an Unknown result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_USER_NOT_AUTH (8) | saf78_RS_NORMAL (0) | Authorization is denied (this is a Deny result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_DATABASE_ERROR (92) | saf78_RS_NORMAL (0) | Authorization failed because the ESM Module or its associated ESM was unable to process the request (this is a Fail result)
Parent topic: Result Codes in the ESF API Parameter Block


Typical Result Codes for Admin

For an Admin request, the most common result code triplets are listed in the table below. These will generally be suitable for most ESM Modules.

An Admin request can succeed or fail, or it can be ignored if the ESM Module does not implement the requested administration subcommand. (If the module determines that it cannot process the request because of an unsuitable or missing parameter, it can fail or ignore the request as the author feels is appropriate.) The return codes below are classified as Success, Failure, or Ignored results.

rc | return | reason | Meaning
saf78_SAF_RC_SUCCESS (0) | saf78_RC_NORMAL (0) | saf78_RS_NORMAL (0) | The request was processed, no additional information (this is a Success result)
saf78_SAF_RC_NOT_COMPLETE (4) | saf78_RC_NO_DECISION (0) | saf78_RS_ESM_NOT_CALLED (0) | The ESM Module does not implement this procedure (this is an Ignored result)
saf78_SAF_RC_NOT_COMPLETE (4) | saf78_RC_NO_DECISION (0) | saf78_RS_ESM_DECLINED (4) | The ESM Module declined to process the request (this is an Ignored result)
saf78_SAF_RC_NOT_COMPLETE (4) | saf78_RC_KEYWORD_ERROR (4) | saf78_RS_KEYWORD_UNKNOWN (4) | The request specified a parameter keyword that the ESM Module does not recognize (this is an Ignored result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_VALUE_ERROR (4) | saf78_RS_VALUE_INVALID (4) | The request specified a parameter value that is not valid for this ESM Module or its ESM (this is a Failure result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_VALUE_ERROR (4) | saf78_RS_VALUE_LENGTH (8) | The request specified a parameter value that was too long or short for this ESM Module or its ESM (this is a Failure result)
saf78_SAF_RC_FAILURE (8) | saf78_RC_DATABASE_ERROR (92) | saf78_RS_NORMAL (0) | The ESM Module or its associated ESM was unable to process the request (this is a Failure result)
Parent topic: Result Codes in the ESF API Parameter Block


Glossary

  • ACE
  • ACEE
  • ACL
  • ADAM
  • ADSI Edit
  • Auditing
  • CA-ACF2
  • CA-TopSecret
  • CLASS
  • CSD
  • ESF
  • ESM
  • LDAP
  • LDIF
  • RACF
  • Resource
  • SAF
  • 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


ACEE

Access Control Environment Element: on the mainframe, a data structure that contains access control information for a task; in MF Server, a data structure that holds security information for a user (or potentially other actor).
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


CA-ACF2

An alternative to RACF.
Parent topic: Glossary


CA-TopSecret

An alternative to RACF.
Parent topic: Glossary


CLASS

In Micro Focus security terms, a CLASS is used to identify a collection of ENTITIES.
Parent topic: Glossary


CSD

CICS System Definiton (definition stored in Enterprise Server in DFHDRDAT / DFHDRDAT.IDX)
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


RACF

Resource Access Facility, IBM's proprietorial security mechanism. Also known as z/OS Security Server
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


SAF

System Authorization Facility API, a call interface to z/OS software security functions. The API is a generic interface to the security functions that are typically provided by IBM’s Resource Access Facility (RACF) product. With Enterprise Server, this is typically user verification and resource access authorization.
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

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
  • Using the Audit Manager as a Windows Service
  • Audit Manager Errors
  • Configuring a User Exit
  • Audit Manager APIs
Parent topic: Enterprise Server Security


About the Audit Manager

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, you can run the Audit Manager as a service. To install and configure the Micro Focus Audit Manager service, see To Install the Audit Event Consolidator as a Service (Windows only).
    • 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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin and \bin64 .
  • 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

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

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

You can use a configuration file to configure audit setup. Specify the configuration file with the auditmgr -c command when you start auditing. In a 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
mfaudit.timeout=300
# Sets the duration (in milliseconds) that an event will
# retry writing to output before it times out.
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

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.
    • Maximum size of each audit file in the collection is 20MB.
  • The timeout period for sending events is set to zero; that is, no timeout period is in effect.
  • The location in which the audit files are created is set by the environment variable MFAUDIT_LOGS.
Parent topic: Audit Manager Architecture


Getting Started with Auditing

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

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

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.
    • Maximum size of each audit file in the collection is 20MB.
  • The timeout period for sending events is set to zero; that is, no timeout period is in effect.
  • Location in which the audit files are created is set using 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

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

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

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.
.
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
Configuring the AUDITFILE Emitter


Setting the Audit Output Type

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

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

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.hostname  = <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

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\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

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\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

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

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.hostname = 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

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

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

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

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

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.

Note: See Audit Event Codes for more information on event codes contained in audit output data.
  • mfauditadm command
    Runs the Audit Manager Administration utility, which enables you to access, dump, and create reports for audit information generated by Enterprise Server.
  • To List Audit Event Consolidator Configuration Details
  • 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
  • To Dump All Audit Files in a Collection
  • To Dump an Audit File
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
Audit Event Codes


mfauditadm command

Runs the Audit Manager Administration utility, which enables you to access, dump, and create reports for audit information generated by Enterprise Server.
Important: Execute mfauditadm at the command line or in a batch file from an Enterprise Server command prompt.

Syntax:

mfauditadm {[-n instance-name |
            [-p [-n instance-name | -f dump-audit-file]] |
            [-r [[-date yyyy/mm/dd] [-time hh.mm[.ss[.nnn]]
              [-c] [-d] [-o output-file-name] -f report-audit-file]
            [-d [-c] -f dump-audit-file]}

Parameters:

-n instance-name
Specifies the name of the audit event consolidator instance, which is the name that applications use to communicate with the audit event consolidator.
-p
Make the active audit file available for dumping.
-f report-audit-file
An audit file in the collection for which reports are to be generated.
-c
Generate a report for each available file in the collection.
-f dump-audit-file
The audit file to be dumped or to be made available for dumping.
-r
Generate a report.
-date yyyy/mm/dd
In the generated report file, include only events on the given date.
-time hh.mm[.ss[.nnn]]
In the generated report file, include only events from the given time.
-o output-file-name
Name of the report file to be created. If not specified, the report file name is derived from the report-audit-file name prefix, plus a .txt extension. For example, if report-audit-file filename is mfaudit.DOCTEST.aud_3, the report file created is mfaudit.DOCTEST.txt.
-d
Mark the file as dumped or mark each audit file available for dumping as dumped.

Examples:

See Related Tasks below.

Parent topic: Accessing Audit Data
Related tasks
To List Audit Event Consolidator Configuration Details
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 and Generate a Report for an Audit File
To Dump and Generate Reports for All Audit Files in a Collection
To Dump All Audit Files in a Collection


To List Audit Event Consolidator Configuration Details

You use the Audit Manager Administration command line utility to do this.

Syntax:

mfauditadm [-n instance-name]

Parameter:

-n instance-name
Specifies the name of the audit event consolidator instance, which is the name that applications use to communicate with the audit event consolidator.

Example:

mfauditadm -n myAuditInstance
Parent topic: Accessing Audit Data
Related reference
mfauditadm command


To Generate a Report for an Audit File

Syntax:

You use the Audit Manager Administration command line utility to do this. To generate a report for the active audit file, you must first make it available for dumping. See To Make the Active Audit File Available for Dumping.

mfauditadm -r [-o output-file-name] -f report-file-name [-d]

Parameters:

-r
Generate a report.
-f report-audit-file
An audit file in the collection for which reports are to be generated.
-o output-file-name
Name of the report file to be created. If not specified, the report file name is derived from the report-audit-file name prefix, plus a .txt extension. For example, if report-audit-file filename is mfaudit.DOCTEST.aud_3, the report file created is mfaudit.DOCTEST.txt.
-d
Mark the file as dumped.

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 tasks
To Make the Active Audit File Available for Dumping
Related reference
mfauditadm command
Related information
Accessing Audit Data
Configuring the AUDITFILE Emitter


To Generate a Report for All Audit Files in a Collection

Syntax:

You use the Audit Manager Administration command line utility to do this. To generate a report for an active audit file, you must first make it available for dumping. See To Make the Active Audit File Available for Dumping.

mfauditadm -r [-o output-file-name] -f report-audit-file -c [-d]

Parameters:

-r
Generate a report.
-o output-file-name
Name of the report file to be created. If not specified, the report file name is derived from the report-audit-file name prefix, plus a .txt extension. For example, if report-audit-file filename is mfaudit.DOCTEST.aud_3, the report file created is mfaudit.DOCTEST.txt.
-f report-audit-file
An audit file in the collection for which reports are to be generated.
-c
Generate a report for each available file in the collection.
-d
Mark each audit file available for dumping as dumped.

Example:

mfauditadm -r -c -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 tasks
To Make the Active Audit File Available for Dumping
Related reference
mfauditadm command
Related information
Accessing Audit Data
Configuring the AUDITFILE Emitter


To Dump and Generate a Report for an Audit File

Syntax:

You use the Audit Manager Administration command line utility to do this.

mfauditadm -r [-date yyyy/mm/dd] [-time hh.mm[.ss[.nnn]]]
                -d [-o output-file-name] -f report-audit-file

Parameters:

-r
Generate a report.
-date yyyy/mm/dd
In the generated report file, include only events on the given date.
-time hh.mm[.ss[.nnn]]
In the generated report file, include only events from the given time.
-d
Mark the file as dumped.
-o output-file-name
Name of the report file to be created. If not specified, the report file name is derived from the report-audit-file name prefix, plus a .txt extension. For example, if report-audit-file filename is mfaudit.DOCTEST.aud_3, the report file created is mfaudit.DOCTEST.txt.

Example:

mfauditadm -r -d -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 reference
mfauditadm command


To Dump and Generate Reports for All Audit Files in a Collection

Syntax:

You use the Audit Manager Administration command line utility to do this.

mfauditadm -r [-o output-file-name] -f report-audit-file -c -d

Parameters:

-r
Generate a report.
-o output-file-name
Name of the report file to be created. If not specified, the report file name is derived from the report-audit-file name prefix, plus a .txt extension. For example, if report-audit-file filename is mfaudit.DOCTEST.aud_3, the report file created is mfaudit.DOCTEST.txt.
-f report-audit-file
An audit file in the collection for which reports are to be generated.
-c
Generate a report for each available file in the collection.
-d
Mark the file as dumped.

Example:

mfauditadm -r -c -d -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 reference
mfauditadm command


To Make the Active Audit File Available for Dumping

Syntax:

To access the active file's audit data, you must first make it available for dumping. Afterwards, it is no longer the active file, and you can access the data it contains.

mfauditadm -p [-n instance-name | -f dump-audit-file]

Parameters:

-p
Make the active audit file available for dumping.
-n instance-name
Specifies the name of the audit event consolidator instance, which is the name that applications use to communicate with the audit event consolidator.
-f dump-audit-file
The audit file to be made available for dumping.
Note: If neither -n nor -f are specified to identify the audit file, the command uses the current active file.

Example:

mfauditadm -p -f mfaudit.DOCTEST.aud_5
Parent topic: Accessing Audit Data
Related tasks
To Generate a Report for All Audit Files in a Collection
To Generate a Report for an Audit File
Related reference
mfauditadm command
Related information
Accessing Audit Data
Configuring the AUDITFILE Emitter


To Dump All Audit Files in a Collection

Syntax:

You use the Audit Manager Administration command line utility to do this.

mfauditadm -d -c -f dump-audit-file

Parameters:

-d
Mark the file as dumped or mark each audit file available for dumping as dumped.
-c
Generate a report for each available file in the collection.
-f dump-audit-file
The audit file to be dumped.

Example:

mfauditadm -d -c -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 reference
mfauditadm command


To Dump an Audit File

Syntax:

You use the Audit Manager Administration command line utility to do this.

mfauditadm -d -f dump-audit-file

Parameters:

-d
Mark the file as dumped or mark each audit file available for dumping as dumped.
-f dump-audit-file
The audit file to be dumped.

Example:

mfauditadm -d -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 reference
mfauditadm command
Related information
Accessing Audit Data
Configuring the AUDITFILE Emitter


Using the Audit Manager as a Windows Service

If you have configured the consolidator to use the AUDITFILE Emitter to log audit information, you will need to manage the files that it creates.

To create your own audit emitters to log information, see Audit Emitter Interface.

Note:

The default installation installs the Audit Manager as a service.

  • To Install the Audit Event Consolidator as a Service (Windows only)
  • To Uninstall the Audit Event Consolidator as a Service (Windows only)
Parent topic: Using the Security Audit Manager


To Install the Audit Event Consolidator as a Service (Windows only)

You use the mfauditmgr command line utility to perform this.

Syntax:

mfauditmgr -i [-n name] [-c cfg-file]

Parameters:

-n name | The name of the audit event consolidator instance. This is the name that applications will use to communicate with the audit event consolidator instance. If this option is not specified, the machine name will be used.
-i | Install the audit event consolidator as a service.
-c 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 will be configured as follows:

  • The AUDITFILE emitter will be the only emitter enabled, and its properties will be set to their default values. For details, see AUDITFILE Emitter Properties.
.

Comments:

When starting the service, the -n and -c options may also be specified in the service's Start Parameters entry field (right-click on the Micro Focus Audit Manager service in the Services Window, and select Properties to bring up the properties dialog. Enter the command-line options in the Start Parameters field and click on the Start button.

Parent topic: Using the Audit Manager as a Windows Service


To Uninstall the Audit Event Consolidator as a Service (Windows only)

Syntax:

You use the mfauditmgr command line utility to perform this.

mfauditmgr -u [-n name]

Parameters:

-n name | The name of the audit event consolidator instance. This is the name that applications will use to communicate with the audit event consolidator instance. If this option is not specified, the machine name will be used.
-u | Uninstall the audit event consolidator as a service.
Parent topic: Using the Audit Manager as a Windows Service


Audit Manager Errors

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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
  • Sample file auditfile_exit.c
Parent topic: Using the Security Audit Manager


AUDITFILE User Exit

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 Sample file auditfile_exit.c for a sample user exit calling the AUDITFILE emitter.

Parent topic: Configuring a User Exit
Related reference
Sample file auditfile_exit.c
Setting AUDITFILE Emitter Properties
Configuring the AUDITFILE Emitter


Sample file auditfile_exit.c

The following sample .c code is a user exit that calls the AUDITFILE emitter.

/*******************************************************************************
 *
 * Copyright (C) 1984-2015 Micro Focus International Ltd.
 * All rights reserved.
 *
 ******************************************************************************/

#ifdef _WIN32

# define DLLEXPORT	    __declspec(dllexport)

#else  /* _WIN32 */

# define DLLEXPORT

#endif /* _WIN32 */

#include <string.h>
#include <stdarg.h>
#include <stdio.h>

#include "mfaudit.h"

/******************************************************************************/
/*  AUDITFILE emitter exit						      */
/*									      */
/*  AUDITFILE_EMITTER_EXIT(cobuns32_t function,				      */
/*			   cobuns8_t  *emitter_name,			      */
/*			   ...)						      */
/*									      */
/*  On input:								      */
/*									      */
/*	function	=   exit function				      */
/*									      */
/*	emitter_name	=   emitter instance name			      */
/*									      */
/*	...		=   dependent upon exit function		      */
/*									      */
/*  On output:								      */
/*									      */
/*	<nothing>							      */
/*									      */
/*  Function returns:							      */
/*									      */
/*	0		=   normal completion				      */
/*	non-zero	=   dependent upon exit function		      */
/******************************************************************************/
DLLEXPORT cobrtncode_t
AUDITFILE_EMITTER_EXIT(
    cobuns32_t	function,
    cobuns8_t	*emitter_name,
    ...)
{
    va_list	args;
    cobuns8_t	*filename;

    va_start(args, emitter_name);

    switch(function)
    {
    case AUDITFILE_EXIT_FUNC_INIT:
        printf("Initialising emitter %s\n", emitter_name);
        break;

    case AUDITFILE_EXIT_FUNC_DEINIT:
        printf("De-initialising emitter %s\n", emitter_name);
        break;

    case AUDITFILE_EXIT_FUNC_FILE_ACTIVE:
        filename = (cobuns8_t *)va_arg(args, cobuns8_t *);
        printf("Emitter %s; active file %s\n", emitter_name, filename);
        break;

    case AUDITFILE_EXIT_FUNC_FILE_FULL:
        filename = (cobuns8_t *)va_arg(args, cobuns8_t *);
        printf("Emitter %s; full file %s\n", emitter_name, filename);
        break;

    case AUDITFILE_EXIT_FUNC_NO_FILES:
        printf("Emitter %s; no available files\n", emitter_name);
        break;

    default:
        printf("Emitter %s; unknown function %d\n", emitter_name, function);
        break;
    }

    va_end(args);
    return 0;
}
Parent topic: Configuring a User Exit
Related reference
AUDITFILE User Exit


Audit Manager APIs

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 Event Codes
  • 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

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)
21 | 78-AUD-RET-TIMEDOUT | Sending of event timed out
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

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 Event Codes

These are the audit events emitted by the External Security Facility (ESF) and Micro Focus Directory Server (MFDS). Events from ESF use the "MF.SAFMGR" component ID; those from MFDS use "MF.MFDS".

ESF Events: Category and Type Codes, and Parameters

In the following list, the first number is the event category and the second the type. Events are grouped by category, so "1 x" is the collection of events in category 1, the category for events generated by the audit facility itself.

For events with parameters, there is also a short list of those parameters, either for the specific event or in the description of a group of events.

Category 0: Unknown

No events defined

Category 1: Audit facility specific

1 0
Audit manager starting.
  • Shared memory area name.
  • Server type (1 = multiprocess CTF server).
1 1
Audit manager stopping.
  • Shared memory area name.
1 2
Deactivate file.
The following are MFDS-only:
1 200
Page request
  • Receive count
  • User ID
  • Request description (format varies)
1 201
Logon request
  • Receive count
  • User ID
  • Return code (prefixed with "Logon attempt, rc=")

Category 2: System

2 0
Component (ESF or MFDS) Initializing
  • MFDS parameter:
    • String "MFDS auditing starting..."
  • No ESF parameters
2 1
Component Started.
2 2
Component Terminating.
  • MFDS parameter:
    • String "MFDS Request processor terminating."
  • No ESF parameters
The following are ESF-only:

Unless otherwise indicated, their parameters are:

  • Exit point.
  • 1 = Exit has stopped processing of the request.
  • Request RC value after exit returned.
  • Request return value after exit returned.
  • Request reason value after exit returned.
2 3
User exit called.
2 4
User exit halted processing of the request.
2 5
User exit returned an error.
The following are MFDS-only:

Unless otherwise indicated, their parameters are:

  • Receive count
  • Object class
  • Object name
2 3
Auditing turned on
  • Receive count
  • Object class
  • String "MFDS auditing starting..."
2 4
Auditing turned off
  • Receive count
  • Object class
  • String "MFDS auditing stopped..."
2 100
Found Server
2 101
Found Comms Server
2 102
Found Listener
2 103
Found Handler
2 104
Found Package
2 105
Found Service
2 106
Found XRM
2 107
Found JES Initiator
2 108
Found JES Printer
2 109
Found IMS MPR
2 110
Found MQL
2 120
Found ESM
2 121
Found User
2 122
Found Group
2 123
Found Resource Class
2 124
Found Resource Entity

Category 3: Security API request

Only emitted by ESF.

3 0
VERIFY
  • User ID
  • Signon group
3 1
AUTH
  • User
  • Resource class
  • Resource entity
  • Requested access
3 2
XAUTH
  • User
  • Resource class
  • Resource entity
  • Requested access

Category 4: Administration request

Only emitted by ESF.

These all use the same parameterization. They include three fixed parameters, followed by a variable number of parameters, with one for each key-value pair included in the request. (For password keys, the key is included but the value is omitted.) Requests that are too long for a single audit event are split into a series of "continuation" events (category 5, type 3). The fixed parameters are:

  • Audit command name
  • Audit command code
  • User
4 0
List
4 1
Add
4 2
Delete
4 3
Alter
4 4
Set password
4 5
Set options

Category 5: Other request

Only emitted by ESF.

5 0
Update notify. Currently not used.
5 1
Audit success (a SAFROUTE AUDIT request with type=1)
  • User
  • Entity string supplied by caller
  • Log string supplied by caller
5 2
Audit failure (a SAFROUTE AUDIT request with type=2)
  • User
  • Entity string supplied by caller
  • Log string supplied by caller
5 3
Parameter information (continuation of large audit event)
  • Parameter ID
  • Chunk number
  • Data chunk

Category 6: Allow

Only emitted by ESF.

6 0
Verify success
  • User ID
  • Signon group
  • 1 = resolved using the ESF cache
6 1
Verify allowed for unknown user
  • User ID

Category 7: Deny

Only emitted by ESF.

Unless otherwise indicated, the Verify-deny events use these parameters:

  • User ID
  • Signon group

and the Auth/XAuth-deny events use:

  • User ID
  • Resource class
  • Resource entity
7 0
Verify deny: Invalid password
7 1
Verify deny: Expired password
7 2
Verify deny: Password change rejected
7 3
Verify deny: User unknown
7 4
Verify deny: User not in requested signon group
7 5
Verify deny: Other failure
7 6
Auth deny
7 7
XAuth deny

Category 8: ESM error

Only emitted by ESF.

Unless otherwise indicated, their parameters are:

  • ESM number
  • ESM name
  • ESM return code
  • Error description
8 0
Verify error
8 1
Auth error
8 2
XAuth error
8 3
Admin error
  • Admin command name
  • Command code
  • User
8 4
Update error
  • User
  • ESM number
  • Update action code
  • Resource entity

Category 9: Security request success

Only emitted by ESF.

9 0
Admin success
  • Admin command name
  • Command code
  • User
9 1
Update success
  • User
  • ESM number
  • Update action code
  • Resource entity
Parent topic: Audit Manager APIs
Related concepts
Accessing Audit Data


Audit Configuration APIs

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.

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
TIMEOUT | the duration (in milliseconds) that an event will retry to be written to output before it times out.

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.

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 | the 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
TIMEOUT | the duration (in milliseconds) that an event will retry to be written to output before it times out.
Note: Other property names may be set, but they will be ignored by the facility.
property-value
The alphanumeric or numeric (in the case of TIMEOUT) value of property-name.

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

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.

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
78-AUD-RET-TIMEDOUT

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.

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.

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
AUDIT_RET_TIMEDOUT

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

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.

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.

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

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.

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.

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.

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

On client systems such as COBOL Web Services clients, and clients that use client/server binding, ES/MSS Remote Job Entry, 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 directory that corresponds to your platform. Enterprise Developer stores mf-client.dat in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin and \bin64 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 %ProgramFiles(x86)%\Micro Focus\DemoCA. To find out the directory, look up the registry key HKEY_LOCAL_MACHINE\Software\Micro Focus\DemoCA\1.0\Setup\DemoCAFolder .
    • 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

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 %ProgramFiles(x86)%\Micro Focus\DemoCA 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:
    copy 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

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 %ProgramFiles(x86)%\Micro Focus\DemoCA 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

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 %ProgramFiles(x86)%\Micro Focus\DemoCA. To find out the directory, look up the registry key HKEY_LOCAL_MACHINE\Software\Micro Focus\DemoCA\1.0\Setup\DemoCAFolder.

  7. Click OK.
Parent topic: Configuring Secure Communications for Client Applications


Setting Up Secure Communications

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

  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

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 %ProgramFiles(x86)%\Micro Focus\DemoCA. To find out the directory, look up the registry key HKEY_LOCAL_MACHINE\Software\Micro Focus\DemoCA\1.0\Setup\DemoCAFolder.

  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

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

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

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin or \bin64 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

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

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

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

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 <path name to directory> to use a directory of CA root certificates.
  • -CAfile <path and file name> 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

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

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

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

By default, the Micro Focus Demo CA installation file, DemoCA_Setup.exe is located in %COBDIR%\bin.

To install Micro Focus Demo CA:

  1. Run DemoCA_Setup.exe.
  2. Follow the prompts in the install wizard.
    Note: The values that you set in the installation screen define the default distinguished name (DN) for the sample certificates created in the Demo CA.
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

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 %ProgramFiles(x86)%\Micro Focus\DemoCA:

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

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

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?

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

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

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 contains the public key from the certificate request.

These scripts are supplied with Micro Focus Demo CA and are by default in %ProgramFiles(x86)%\Micro Focus\DemoCA after you have run the Micro Focus Demo CA installation.

To confirm the Windows directory with which they have been installed, look up the registry key: HKEY_LOCAL_MACHINE\Software\Micro Focus\DemoCA\1.0\Setup\DemoCAFolder.

Parent topic: Tutorial: Requesting and Issuing Server Certificates
Related information
Requesting a Server Certificate
Issuing a Server Certificate


Requesting a Server Certificate

Prerequisites

Before you request a certificate, you must:

  • Install Micro Focus Demo CA, which is supplied with Enterprise Developer, and by default is located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin .

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. With administrative privileges, run the batch utility create_srv_req.cmd, located in %ProgramFiles(x86)%\Micro Focus\DemoCA 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 Name: Palo Alto
Organization Name: Bloggs Widgets Inc
Organizational Unit Name: Marketing
Common Name: svr-blogw
Email Address: bloggs@widgets.com

    The details you enter are included in your server certificate to identify you.

  4. At the A 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. Press Enter at the next prompt also.
  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

In this section, you issue the server certificate.

  1. Run the batch file sign_srv.cmd, which is in %ProgramFiles(x86)%\Micro Focus\DemoCA by default. When the batch file asks if you are 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 pass phrase, enter the CA pass phrase 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 command:
    openssl x509 -in newcerts\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 directory, 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

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

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 provides 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

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

In this section, as server administrator, you install the server certificate on the server so that remote Web users can 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 %ProgramFiles(x86)%\Micro Focus\DemoCA.
  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

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin and \bin64 . 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 pass phrase.
  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

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 HTTP Echo 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

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 directory. You install this certificate as follows:

Note: These steps are applicable if you are using Internet Explorer (version 9); steps required for other versions of Internet Explorer or other browsers may differ.
  1. In Internet Explorer, click Tools > Internet Options > Content > Certificates. Go to the Trusted Root Certification Authorities tab and click Import.
  2. Use the wizard to 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. Other browsers can handle several types, and so they may also be listed.
  3. Look down the list under Trusted Root Certification Authorities. 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

Now that the CA's certificate is installed, you should be able to connect from the client Web browser.

Note: These steps are applicable if you are using Internet Explorer (version 9); steps required for other versions of Internet Explorer or other browsers may differ.
  1. Try to connect again. In the Web browser, enter https://localhost:9443.
  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. Since this is in fact the desired Web site, click Continue to this website (not recommended) .

    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

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.

Note: These steps are applicable if you are using Internet Explorer (version 9); steps required for other versions of Internet Explorer or other browsers may differ.
  1. In Internet Explorer, click Tools > Internet Options > Content > Certificates.
  2. Click the Trusted Root Certification Authorities tab, locate 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

The openssl.exe utility is installed by default in the directory: %ProgramFiles(x86)%\Micro Focus\DemoCA. 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

The OpenSSL utility is installed by default in %ProgramFiles(x86)%\Micro Focus\DemoCA.The 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 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

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 .

If you receive a warning message like "WARNING: can't open config file: /usr/local/ssl/openssl.cnf" from the OpenSSL utility, set the environment variable OPENSSL_CONF to the location of a suitable openssl.cnf file. One is included with the Micro Focus DemoCA, in the main directory of the DemoCA installation. For example:

Windows:

set OPENSSL_CONF=C:\Program Files (x86)\Micro Focus\DemoCA\openssl.cnf

UNIX:

export OPENSSL_CONF=$COBDIR/DemoCA

Note: This message is only a warning; the openssl command may still perform the function you requested. The openssl.cnf file is primarily used to set default values for the CA function, key sizes for generating new key pairs, and similar configuration. Consult the OpenSSL documentation available at openssl.org for more information.

OpenSSL CA function openssl.org

Parent topic: Information on OpenSSL


Algorithms

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

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 failing 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

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

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.

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?

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

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

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

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

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

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

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

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

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.

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

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?

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?

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?

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?

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?

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?

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

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?

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

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

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

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

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

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

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

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

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

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

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

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 %ProgramFiles%\Micro Focus\DemoCA\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

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

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

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

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

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.
  • X.509
  • PKCS Standards
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: X.509


X.509

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

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

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

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

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

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

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

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

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

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

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

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)

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

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

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

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

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)

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.
  • Overview
  • Base64 Encoding
  • SSLeay
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: Overview


Overview

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • 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

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

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

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

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

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

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
Parent topic: Copyright and Legal Information


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


Mainframe Support for Deployed Applications

  • MSS Configuration and Administration
    Mainframe Subsystem Support (MSS) enables CICS, IMS and JCL applications that have been migrated from the mainframe to be maintained, developed and deployed on Windows or UNIX.
  • CICS Support Tasks
  • IMS Support Tasks
  • JCL Support Tasks
  • Reference for MSS Deployment
    Contains information on general and CICS commands, data conversion, resource definitions, and supplied transactions.
Parent topic: Micro Focus Enterprise Server 2.3 Update 1 for Windows


MSS Configuration and Administration

  • Introduction to Mainframe Subsystem Support
  • CICS Support
  • JCL Support
  • IMS Support
  • Using Fileshare with Enterprise Server
  • Running EZASOKET Applications on Enterprise Server
Parent topic: Mainframe Support for Deployed Applications


Introduction to Mainframe Subsystem Support

  • What is Mainframe Subsystem Support?
  • Licensing
  • Developing and Testing the Application
  • Running the Application
  • Event Manager
  • About SSTM
    Describes the Subsystem Started Task Manager
  • To enable JCL support from a CICS or IMS subsystem
    Describes how to enable JCL support from within a CICS or IMS subsystem.
  • Security implications with the SSTM subsystem
    Describes the access rights that the user ID needs in order to use SSTM
  • SSTM subsystem status messages
    Describes status messages associated with the SSTM subsystem
Parent topic: MSS Configuration and Administration


What is Mainframe Subsystem Support?

Mainframe Subsystem Support (MSS) is a facility that enables CICS, IMS and JCL applications that have been migrated from the mainframe to be maintained, developed and deployed on Windows or UNIX platforms.

You use the COBOL development system Enterprise Developer for maintaining your CICS, IMS and JCL applications. An MSS-specific project type is supplied with the IDE to help you develop such applications. If you are working with CICS, you can edit and compile BMS maps, and also compile the CICS programs, using the Micro Focus CICS preprocessor, which translates the CICS commands into native code. If you are working with IMS, you can edit and generate your DBDs, MFSs and PSBs, and compile your IMS programs. If you are working with JCL, you can edit and create JCL, and build projects containing the programs that the JCL references. When the application is ready to run, you then deploy it to the COBOL run-time server Enterprise Server.

You use Enterprise Server for running your CICS, IMS and JCL applications, for testing and for production use. Enterprise Server also provides facilities for monitoring and controlling your applications and for other tasks such as maintaining CICS resource definitions and viewing the system catalog and spool queues.

Parent topic: Introduction to Mainframe Subsystem Support


Licensing

For information about development licensing, see your Licensing topics. For information about deployment licensing, see Deployment Licensing.

Parent topic: Introduction to Mainframe Subsystem Support


Developing and Testing the Application

The process used by developers using Enterprise Developer as the development environment with Enterprise Server as the deployment environment is as follows:

  1. Use Enterprise Developer to maintain and compile BMS mapsets for CICS or generate DBDs, MFSs and PSBs for IMS.
  2. Use Enterprise Developer to maintain resource definitions.
  3. Maintain and compile CICS, IMS and batch programs in Enterprise Developer.
  4. If the target deployment platform is UNIX, they use the Enterprise Developer Publish option to publish the application to UNIX.
  5. They deploy the application to Enterprise Server.
  6. They debug the application in the Enterprise Developer IDE.

Steps 3 through 6 need to be repeated as required to get the application working correctly.

Developers need to have some familiarity with running programs in Enterprise Server and the facilities provided therein specifically for monitoring CICS, IMS and JCL applications.

Note:

As Enterprise Server only supports upper case API names, care has to be taken when making calls with lower or mixed case names. This is particularly relevant with applications that have been developed on case sensitive operating systems such as UNIX. This problem can be avoided by using the NOCASE directive when compiling the application. This instructs the COBOL compiler to convert external symbols to upper case.

In the case where, for example, an IMS application uses lower or mixed case API names and has moved to a UNIX platform but must also issue calls to platform specific lower or mixed case APIs', the CASE directive can be used, provided the IMS specific symbols are converted from lower or mixed case to upper case.

Parent topic: Introduction to Mainframe Subsystem Support


Running the Application

Once the application is working correctly, administrators look after the running and monitoring of the application in Enterprise Server. They need to:

  • Maintain resource definitions for CICS; they can do this in the development environment. The format is portable between environments. There are also import and export tools which enable the downloading of the definitions into a text file for more convenient editing.
  • Control and monitor the running of the application, within the context of Enterprise Server.

The administration tool ESMAC, Enterprise Server Monitoring and Control, provides facilities for maintaining resource definitions and monitoring and controlling CICS, IMS and JCL applications. Many of its facilities are also available for non-MSS applications running in Enterprise Server. For detailed information about running CICS, IMS and JCL applications in Enterprise Server, see the chapters Administering CICS-enabled Enterprise Servers , Administering IMS-enabled Enterprise Servers and Administering JCL-enabled Enterprise Servers.

You also need to use facilities in the main Enterprise Server interface. For more information see the main Enterprise Server Configuration and Administration Guide .

Parent topic: Introduction to Mainframe Subsystem Support


Event Manager

The JCL support in Mainframe Subsystem Support includes an event manager, which provides support for third-party products such as schedulers.

When an enterprise server is started, it can call a user exit program, which on this first call can register an interest in particular types of events (for example, abends). Then whenever an event of any of the registered types occurs, the event manager will call the user exit program to process it. This user exit program can be a third party tool, such as a scheduler.

For further information, please contact your sales representative.

Parent topic: Introduction to Mainframe Subsystem Support


About SSTM

The Subsystem Started Task Manager (SSTM) provides full JCL functionality within the CICS and IMS subsystems. This JCL functionality is equivalent to that of a task started under z/OS.

CICS
A CICS (MSS) Region typically uses more than one SEP to process online transactions. In the CICS region, each SEP runs the same JCL using the same job name and number. Within the region, all CICS SEPs JCL job activities and their outputs can be found under this one job number. All of the CICS SEPs:
  • Share permanent datasets whether these are allocated via the JCL or via SVC99. The system does not provide any access serialization capabilities. Any non-read access to shared datasets must be serialized, if necessary, by the user.
  • Do not share in-stream (DD * and DD DATA) datasets.
  • Do not share other datasets (temporary and SYSOUT datasets).
  • Contain in the joblog dataset, JCL logged activity incurred by all CICS SEPs with identification of the originating SEPs process id.
IMS
An IMS subsystem uses one SEP for each Message Processing Region (MPR) and will typically have more than one MPR. Each MPR has a unique job number, but will very likely have the same job name. Each MPR’s activity and outputs are independent as with batch jobs, and can be found under the MPR’s job number.

When SSTM is enabled, you can specify an application parameter (APARM) in the JCL for an IMS MPR. The APARM is available to the AIBTDLI INQY ENVIRON call from IMS applications and data capture exit routines. The value of the APARM is taken from the JCL when the first message is processed in the MPR. All MPRs share the same JCL file.

Parent topic: Introduction to Mainframe Subsystem Support


To enable JCL support from a CICS or IMS subsystem

Note: The specified JCL job stream must contain only one step. A multiple step job is treated as an error and will fail SSTM initialization.
Note: Setting the SSTM is required for the CICS spooling facility. That is, if you want to use the CICS SPOOLOPEN OUTPUT, SPOOLWRITE, SPOOLCLOSE commands, etc.

In the Enterprise Server (ES) configuration, you enable JCL support by setting the ES_SSTM_ssss environment variable to a fully qualified path to the JCL used to initialize the SSTM environment. In the environment variable,ssss is CICS or IMS, depending on the environment that you want to initialise.

From the Enterprise Server Administration Console, set the ES_SSTM_ssss to the fully qualified path of the JCL used to initialize the SSTM Environment; for example:
  • CICS environment:
    ES_SSTM_CICS=c:\es\sstm\jcl\sstmcics.jcl
  • IMS environment:
    ES_SSTM_IMS=c:\es\sstm\jcl\sstmims.jcl

The default program attributes used for the SSTM are a mainframe dialect, AMODE(31) program with a character set derived from the value of the environment variable MF_CHARSET. If this variable is not set, then a value of ASCII is used. You can tailor the attributes to suit your requirements by creating a simple 'no-op' program and compiling it with the attributes you require. The program is not run, but the attributes are used, and are shown in the JESYSMSG output log for the job; for example:

JCLCM0199I Program MFJBR14 is COBOL VSC2 ASCII Big-Endian AMODE31

Example JCL

The following is an example JCL code for CICS. In the code:
  • The job name SSTMJCL is not significant - any valid job statement may be used.
  • The step name CICS is not significant - any valid step name may be used.
  • The program name in the PGM= entry must be syntactically correct, but it does not need to exist.
  • The DDname SHAREDD1 is shared across CICS SEPs because it refers to a permanent dataset.
  • The other DDnames in the example refer to datasets allocated by JES during SEP initialisation, and are therefore not shared, but are local to each SEP. The dataset referred to by the DDname LOCALDD1 is temporary, and will not be retained when CICS is shut down, but it could be used by any program during the life of the CICS region.
  • When executing PL/I programs under CICS the output from PUT statements directed to the SYSPRINT file (either implicitly or explicitly) will not appear in the SSTM job, but will instead be routed to the internal TDQ named CPLI.
  • The DDname JOBSUB is directed to the JES internal reader. This DD statement could be used to submit jobs to JES using direct I/O from a COBOL or PL/I program, instead of using the TDQ or SPOOL facilities provided with CICS. There is no significance to the DDname JOBSUB - any valid DDname can be used to submit jobs, provided it is directed to SYSOUT=(*,INTRDR).
//SSTMJCL JOB 'CICS JOB',MSGCLASS=A
//CICS     EXEC PGM=NOTUSED
//SYSOUT   DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SHAREDD1  DD DSN=SHARED.ACROSS.SEPS1,DISP=(MOD,CATLG)
//LOCALDD1  DD DSN=&&SEPLOCAL,DISP=NEW
//JOBSUB    DD SYSOUT=(*,INTRDR)
Parent topic: Introduction to Mainframe Subsystem Support


Security implications with the SSTM subsystem

The user ID under which the Enterprise Server session runs requires sufficient authority to submit and execute JCL. Any writes that the JCL makes to the internal reader via a CICS trancode are submitted as the currently logged on user. If no-one is logged on, these are submitted as Default CICS User ID.

Note: If you have overridden your Default CICS User with another user ID, or you have created a new Default CICS User ID, then you need to ensure that this user ID has sufficient authority to submit and execute JCL.
Parent topic: Introduction to Mainframe Subsystem Support


SSTM subsystem status messages

JES000040I SSTM environment established successfully.!
Indicates that the SSTM environment initialized successfully.
JES000041E SSTM initialization failure %1$s!
Indicates likely JCL errors. Check the appropriate job log and console log for additional information. Appropriate CTF traces will contain information that may help in diagnosing the problems.
JES000042I SSTM not enabled: %1$s!
Either you chose not to initialize SSTM environment, or you have misspelled the environment variable name.
JCLCM0199I job-number job-name Program program-name is cobol-dialect char-set byte-order amode-type
Displays the characteristics (dialect, character set, byte order, and AMODE type) of the program being executed.
Parent topic: Introduction to Mainframe Subsystem Support


CICS Support

  • Installation Verification
  • Configuring CICS-enabled Enterprise Servers
  • Resource Definitions
  • Configuring CICS for Security
  • Configuring CICS for Databases
  • Intersystem Communication
  • Setting Up Communications with Mainframe CICS Regions
  • Configuring CICS Terminals and Printers
    Describes how to set up and configure terminals and printers for the CICS support in Enterprise Server.
  • CICS Web Interface Support
  • Transaction class (TRANCLASS) support
    Transaction classes give you a mechanism to limit the number of CICS tasks in your system.
  • Modernizing CICS Applications
  • Administering CICS-enabled Enterprise Servers
  • MSS Aspects of Troubleshooting
  • CICS Support Tasks
Parent topic: MSS Configuration and Administration


Installation Verification

This chapter describes the installation verification procedure (IVP) you can use to check that the Mainframe Subsystem Support software is installed and working properly. The installation verification procedure involves starting an enterprise server and terminal emulation, signing on and running a transaction.

The steps involved in running the installation verification procedure are:

  1. Start Enterprise Server Administration
  2. Import an enterprise server: the installation software comes with an enterprise server configuration file that you can import and use for installation verification.
  3. Start the enterprise server
  4. Connect to the enterprise server
  5. Run the installation verification procedure

Unless stated otherwise, the information in the related topics applies whether you are running the installation verification procedure under Enterprise Server for UNIX or Enterprise Server for Windows.

  • Starting Enterprise Server Administration
  • Configuring an Enterprise Server
  • Importing the Installation Verification Enterprise Server
  • Starting the Enterprise Server
  • Connecting to the Enterprise Server
  • Running the Installation Verification Procedure
Parent topic: CICS Support


Starting Enterprise Server Administration

To start Enterprise Server Administration from the Start menu. Click Start > All Programs > Micro Focus Enterprise Server > Enterprise Server Administration.

Parent topic: Installation Verification


Configuring an Enterprise Server

Once you have started Enterprise Server Administration, you need to configure an enterprise server to enable it to run CICS applications and to specify the location of the files it will need.

To configure an enterprise server for use with the installation verification procedure:

  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. On the Server > Properties > General tab in the Configuration Information, type an environment specification for locating the CICS files into. For example, if your project files are all in subdirectories under c:\tutorials\CICS, type:
    [ES-Environment]
CICSPROJ=c:\tutorials\cics

    This sets a value for $CICSPROJ.

  3. Click Properties > MSS.
  4. Specify DFH\$IVP in System Initialization Table.

    Note the use of the slash (\) character to escape the dollar sign.

  5. Specify the location of the transaction programs in Transaction Path, for example:

    $CICSPROJ\mto-bms\debug

  6. Specify the location of the data files in VSAM File Path, for example:

    $CICSPROJ\mto-bms

  7. Specify the location of the BMS maps in Map Path, for example:

    $CICSPROJ\mto-bms

  8. Click OK.

    At this point you have enabled CICS support for this enterprise server and specified the location of the relevant files. The directory names used in the examples above are for illustration only - you should change them to use the directories in which the installation verification procedure files are installed on your system.

  9. Click the Listeners tab.
  10. Click Add in the Listeners column for Communications process 1.
  11. Specify the following information to enable you to use a TN3270 emulator:
    Field | Value
    Name | tn3270
    Endpoint address | *.nnnn, where nnnn is between 5000 and 65535. Check with the system administrator to ensure you choose a number that is not used by other applications.
    Supported Conversation Type | Check TN3270
  12. Click Add.
Parent topic: Installation Verification


Importing the Installation Verification Enterprise Server

The installation software comes with an Enterprise Server configuration file. You can import this file and use the server that it configures for installation verification.

To import the Enterprise Server installation verification configuration file:

  1. On the Enterprise Server Administration screen, under Actions at the left, click Import to display the Import server information screen. The Recent Directories field displays two entries. For example, with Windows XP, the verification enterprise server entry is:

    C:\Documents and Settings\All Users\Application Data\Micro Focus\NetExpress\6.0\MFDS\MSSIVP\

  2. Select the verification enterprise server entry and click Select and then click Next.
  3. Click Next three more times to accept the default settings, then on the Import server information (Page 4 of 4) screen, click OK.
  4. Select the Listeners tab, and verify the following information to enable you to use a TN3270 emulator:
    Field | Value
    Name | tn3270
    Endpoint address | The default endpoint address is 9010. Check with the system administrator that this is not used by other applications. If it is, configure another endpoint address to use.
    Supported Conversation Type | Check TN3270
Parent topic: Installation Verification


Starting the Enterprise Server

Having enabled the enterprise server for CICS applications and specified the location of the files required for the installation verification procedure, the next step is to start the enterprise server.

To start the enterprise server for use with the installation verification procedure:

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

    The value in Current Status changes to "Starting". If you have Show local console checked on the Edit Server page, the enterprise server console daemon window appears indicating the progress of the process of starting the server.

  2. After a few seconds, click Refresh on the Home page.

    The value in Current Status changes to "Started".

Parent topic: Installation Verification


Connecting to the Enterprise Server

Once you have configured and started the enterprise server, you need to start a 3270 emulator from which you can run the installation verification procedure.

To connect to the enterprise server:

  1. Start a TN3270 emulator.
  2. Specify the following connection information (if appropriate):
    Field | Value
    Host name | The name of the computer the enterprise server is running on. This is localhost if it is the current machine.
    Port | The number you specified for the field Endpoint address in the section Configuring an Enterprise Server.
  3. Connect.
Note:

We recommend that you use a Telnet 3270 (TN3270) client such as Micro Focus RUMBA .

Parent topic: Installation Verification


Running the Installation Verification Procedure

This section describes how to run the installation verification procedure once you have configured and started the enterprise server and connected to it with a 3270 emulator. When you first connect, a 3270 terminal is displayed with a screen prompting you for a USERID and PASSWORD.

To run the installation verification procedure:

  1. Press Clear (3270 key).

    The display clears.

  2. Enter the following command:
    CFCR ACCTFIL

    The following messages are displayed:

    Base - ACCTFIL KSDS Key 1 for 5 VARIABLE 63 to 383
ACCTIX     ALTR   Key    6 for   12

CFCR - File successfully created
  3. Press Clear (3270 key).

    The display clears.

  4. Enter the following command:
    acct

    The following screen is displayed.

    Figure 1. Running the Installation Verification Procedure
    Running the Installation Verification Procedure

    You can now add a record to the demonstration account file.

  5. Press Tab until the cursor is positioned in the field immediately following the label REQUEST TYPE.
  6. Type A. The cursor automatically moves ahead to the ACCOUNT field.
  7. Type 22222; then press Enter.
  8. Fill in the fields as follows:
    Field | Value
    SURNAME | SMITH
    FIRST | JOHN
    MI | S
    TITLE | MR
    TELEPHONE | 501234
    ADDRESS (1) | 59 THE COURT
    ADDRESS (2) | WOODED AVENUE
    NO. CARDS ISSUED | 1
    DATE ISSUED | 03 04 98
    REASON | N
    CARD CODE | X
    APPROVED BY | GGC

    Other fields are optional, so you can leave them blank.

  9. Press Enter.
  10. Display the record you have just entered by typing SMITH into the SURNAME field and pressing Enter.
  11. Press Clear (3270 key).

    The display clears.

  12. Enter exit to disconnect the 3270 emulator.
  13. In the table of servers on the Home page of Enterprise Server Administration, find the row for the server that you are using, and click Stop in the Current Status column.

    The value in Current Status changes to "Stopping". If you have Show local console checked on the Edit Server page, the enterprise server console daemon window appears indicating the progress of the process of stopping the server. After a few seconds the value in Current Status changes to "Stopped".

Parent topic: Installation Verification


Configuring CICS-enabled Enterprise Servers

Descriptions of some of the ways in which CICS-enabled enterprise servers can be used, the information needed to control enterprise server processing and how to create and configure CICS-enabled enterprise servers.

  • Overview
  • Shared Memory Area
Parent topic: CICS Support


Overview

A CICS-enabled enterprise server equates to a CICS region. On a mainframe, CICS regions are used for a variety of purposes, such as separating departmental applications or projects, and isolating the impact of failures by separating resources into terminal-owning regions, application-owning regions and file-owning regions. MSS-enabled enterprise servers can be used in similar ways.

You do not need to define services, request handlers or implementation packages in order to run migrated CICS applications in an MSS-enabled enterprise server. However, you should not delete the system services and request handlers that are automatically associated with an enterprise server when you create it.

You can, if you wish, run non-CICS applications such as Web services alongside CICS applications in an MSS-enabled enterprise server.

Configuring a CICS-enabled enterprise server is very like configuring any enterprise server - see Enterprise Server Instance Configuration Issues.

The differences are listed and explained in the following topics.

Parent topic: Configuring CICS-enabled Enterprise Servers
Related information
Enterprise Server Instance Configuration Issues


Shared Memory Area

Because an MSS-enabled enterprise server contains more types of object than a non-CICS enabled enterprise server, there are more objects to take into account when you are deciding how much space to allocate to the shared memory area.
Item | Calculation
Remote systems
  • Number of sysids x 96
  • Number of sessions x 32
PCT | Number of entries x 48
FCT | Number of entries x 88 + (4 x number of split key components used)
DCT | Number of entries x 48
PPT | Number of entries x 48
Programs (load hold)1 | Number active x (average length + 8)
TST | Number of entries x 32
PLT | Number of entries x (56 + (8 x average number of items in list))
JCT | Number of entries x 48
ICE2 | Number active x 64
AID3 | Number active x 64
Getmain SHARED4 | Number active x (average length + 8)
ENQ5
  • Number active x (24 + average argument length)
  • Number of processes waiting on ENQ x 16
CICS client requests6 | (3270 data stream length + COMMAREA + TEUA + 64) x number of servers
  • The System Initialization Table (SIT)
  • The Startup List
  • Loading DLL files
  • Deferring Loading of PCT Entries
Parent topic: Configuring CICS-enabled Enterprise Servers
1 Programs loaded as data with EXEC CICS LOAD
2 Interval Control Elements. Tasks scheduled for a particular time.
3 Automatic Initiate Descriptor. Tasks awaiting a free service execution process for execution.
4 Areas of memory allocated with EXEC CICS GETMAIN SHARED.
5 User controllable synchronization locks allocated with EXEC CICS ENQ.
6 The buffers calculation is a rule of thumb. Use the average data stream, COMMAREA, and TEUA sizes for the computation. This only works if your system is set up to incur a minimum amount of SEP queueing. The buffers calculation must exceed the maximum size of a single buffer; that is, one that contains maximum data, COMMAREA, and TEUA sizes.

Buffers are short lived and stay in shared storage only if no SEP is available to service the request. Once a SEP is dispatched, the buffer is immediately moved to local process storage and the shared storage is released. Outbound buffers also stay in shared storage for a very short period of time. Outbound, the only delay is for processor dispatch to the supporting terminal process. Once the terminal process is dispatched, the buffer contents are moved to local process storage and the shared storage buffer is released.


The System Initialization Table (SIT)

The System Initialization Table (SIT) specifies how a CICS-enabled enterprise server is to be initialized when it starts up. It determines such things as, but is not limited to:

  • A list of resource groups that are automatically installed at startup (the startup list).
  • Whether the loading of any PCT entries is to be deferred.
  • The System ID that a CICS-enabled enterprise server is to be known by.
  • The number of service execution processes (SEPs) that start for the enterprise server. A SEP equates to a CICS transaction server in a multi-tasking region.
  • Whether any network communications are to be enabled.
  • Whether trace is to be active, and for which features.

Some of the properties of a SIT are shared with the enterprise server definition, for example, the size of shared memory and settings for traces and dumps.

A SIT is defined and stored in a resource definition file (RDF). An RDF can hold any number of SITs. CICS supplies several pre-configured SITs. These can be used as defaults or used as a basis for customizing your own.

Parent topic: Shared Memory Area


The Startup List

The startup list names the resource groups that are to be installed at system initialization. In this way, you can specify which resources are associated with a SIT and therefore which resources are installed when a CICS-enabled enterprise server is started. You can share resources across multiple enterprise servers or you can restrict some resources to a specific enterprise server. No matter what resources are defined in an RDF, a resource is not installed for an enterprise server unless the group that the resource belongs to is specified in the startup list associated with the SIT used to start the enterprise server. (You can, however, use the supplied transaction CINS to install further resource groups once the server is running.)

Assume, for example, that the RDF defines the resources shown below:

Figure 1. Example of resources defined in the RDF
Example of resources defined in the RDF

Starting an enterprise server with the SIT SAMPSIT1 specified will initialize that enterprise server with the two groups SAMPGRP1 and SAMPGRP2. This is because SAMPSIT1 specifies a startup list SAMPLST1 which has only those two groups listed.

Additional groups can be installed to that enterprise server when it is running, without having to stop the server, by using the supplied transaction CINS.

Assuming you have the authority (sign-on security privilege) to run the transaction, enter:

CINS SAMPGRP3

Then the SAMPLIST3 group is installed and made available to enterprise server users.

Parent topic: Shared Memory Area


Loading DLL files

The application's compiler generates DLL files from your source code. In the Windows environment, DLL code is controlled by the operating system. Once a DLL has been loaded, it is locked to the loading process, in this case CICS, and no other process can overwrite the DLL file.

When you modify existing code you need to use the procedure described below to replace an existing DLL file with the new file that you compile. To configure and load a replacement DLL file:

  1. Create a staging folder to hold your updated DLL files, and compile your DLLs to this folder.
  2. On the enterprise server running the CICS application, from the Enterprise Server Administration screen, select the Server > Properties > General tab.
  3. In the Configuration Information field, define an environment variable, ES_STAGING_FOLDER that sets the staging directory. For example, to define the staging directory as D:\CICS\Staging, you would use the following entry:
    [ES-Environment]
ES_STAGING_FOLDER=D:\CICS\Staging

    See the figure below for an example.

  4. Click Apply to set the envfironment variable.
  5. Use the CICS CPMT transaction to set that a new version is available.

    The transaction replaces any existing DLLs that your application uses with the DLLs in the staging directory. For example, to load a new version of MYPROG.DLL, you would use the following CPMT CICS transaction:

    CPMT NE MYPROG

Note:

Use this process only for updating programs that are currently in use by CICS. For new programs, you must copy or compile your new program directly into the appropriate production folder.

Figure 1. Configuring DLL updates
Configuring DLL updates

  • Errors
Parent topic: Shared Memory Area


Errors

All errors generated by the CPMT command are returned in EIBRESP, EIBRESP2 and EIBRCODE.

Table 1. >NOTFND (RESP 13) RESP2 values
Value | Description
1 | The environment variable cannot be resolved.
3 | The length of the file name when added to the staging folder is too big.
4 | The file name plus staging folder is incorrect.
8 | No staging folder has been defined.
12 | Program not found in staging folder.
Table 2. >IOERR (RESP 17) RESP2 values
Value Description
16 A Windows API function has failed. EIBRCODE contains:
  • Pos 1: 'C' to indicate that CopyFileA has failed
  • Pos 2-5: Windows error code in binary
,
Table 3. >PGMIDERR (RESP 27) RESP2 values
Value | Description
7 | Program not found (no PPT entry and program not loaded).,
Parent topic: Loading DLL files


Deferring Loading of PCT Entries

You can control whether to load all PCT entries at startup or to defer the loading of some or all PCT entries until the corresponding transaction ID is entered.

The advantages of loading all PCT entries at startup are:

  • Online execution time of PCT lookup is fast as all definitions are stored in memory.
  • The transactions available in the enterprise server are fixed at startup. Any offline RDF changes or additions are not visible to the enterprise server unless the CINS transaction is run.

These advantages are particularly important in a production environment, where you need fast response times and stable region definition. The disadvantage is that if there are many PCT entries to load, the startup time is increased and the shared memory usage will be high.

You can control the loading of PCT entries with the Defer Install field on the CICS SIT page of ESMAC.

If you defer loading PCT entries, when you enter a transaction ID that is not currently loaded into memory, CICS searches the groups specified in the original startup list in reverse order. If a PCT entry for the transaction ID is found, it is dynamically loaded into memory for subsequent use. If the transaction ID is not found, a TRANSIDERR occurs as normal.

Note: If a group specified as deferred is empty at startup, it will not be searched subsequently for PCT entries.

The following examples assume that resources are defined as shown.

Assume the RDF defines the resources shown below.

Figure 1. Resource Definition File for Example 1
Resource Definition File for Example 1

Using DEFSIT1, the following entries are loaded into memory at startup (in addition to the DFH group entries):

  • (TRN2,PROG2) from DEFGRP1
  • (TRN3,PROG3) from DEFGRP1
  • (TRN4,PROG4) from DEFGRP2
  • (TRN1,PROG5) from DEFGRP2

The entry for (TRN1,PROG5) from DEFGRP2 is used instead of the entry for TRN1 in DEFGRP1. This is because DEFGRP2 occurs later than DEFGRP1 in the startup list.

Assume the RDF defines the resources shown below.

Figure 2. Resource Definition File for Example 2
Resource Definition File for Example 2

Starting the region with DEFSIT2, deferred PCT loading is enabled for all groups in the startup list. No PCT entries are loaded into memory at startup. When the enterprise server is running, if the transaction ID TRN3, for example, is entered from a client, the system will:

  • Search DEFGRP2 for a PCT entry=TRN3. Result: Not found
  • Search DEFGRP1 for a PCT entry=TRN3. Result: Found. Load the definition into memory

Subsequent uses of the transaction ID TRN3 will find the PCT entry in memory, so no searching of the resource definition file takes place. Similarly, if the transaction ID TRN1 is entered from a client, the system searches for and finds the definition in DEFGRP2.

This will find the same definition for TRN1 as shown in Resource Definition File for Example 1 above.

Assume the RDF defines the resources shownbelow.

Figure 3. Resource Definition File for Example 3
Resource Definition File for Example 3

The third type of deferred PCT load allows you to specify the number of groups that will have the loading of their PCT definitions deferred. In this case, the deferred group count is set to 1, so the loading of PCT definitions from DEFGRP2 is deferred.

The number of groups to defer is counted back from the end of the startup list.

In this case, at system startup, the following PCT definitions are loaded into memory:

  • (TRN1,PROG1) from DEFGRP1
  • (TRN2,PROG2) from DEFGRP1
  • (TRN3,PROG3) from DEFGRP1

The definition for transaction ID TRN1 is now taken from DEFGRP1 and not from DEFGRP2.

Parent topic: Shared Memory Area


Resource Definitions

  • Introduction
  • Exchanging Resource Definitions Between Resource Definition Files
  • Maintaining Resource Definitions
  • CICS Resource Definitions
Parent topic: CICS Support


Introduction

The resource definitions stored by MSS are different in both content and form to those stored on the mainframe. Many resource types and attributes that you can define on the mainframe are meaningless in the Windows environment, for example LSRPOOL. MSS recognizes these resource types and attributes but takes no action on them. Conversely, MSS understands some additional attributes that only make sense in the Windows environment, and some of these are mandatory.

The following table lists all the types of resource definition used or recognized by MSS. For each type of resource definition, the name by which it is known in the .rdt file used for exchanging resource definitions with other Enterprise Server with MSS systems is given, followed by an indication of the support provided, then any abbreviation used within the interface and its meanings. Mainframe resource types are listed first, followed by Micro Focus extensions.

Keyword in .rdt file | Used or recognized | Abbreviation | Meaning
CONNECTION | Used |  |
FILE | Used | FCT | file control table
LSRPOOL | Recognized |  |
MAPSET | Recognized |  |
PARTITIONSET | Recognized |  |
PARTNER | Recognized |  |
PROFILE | Recognized |  |
PROGRAM | Used | PPT | program processing table
SESSIONS | Recognized |  |
TERMINAL | Used | Term | terminal
TRANCLASS | Used | TRCLASS | transaction class
TRANSACTION | Used | PCT | program control table
TYPETERM | Used | T-type | terminal type
TDQUEUE | Used | DCT | destination control table
_JOURNAL | Extension | JCT | journal control table
_PGMLIST | Extension | PLT | program load table
_SIGNON | Extension | SNT | signon table
_SIT | Extension | SIT | system initialization table
_STARTUPLIST | Extension |  |
_TEMPSTORAGE | Extension | TST | temporary storage table
_XOPENCOMPAT | Extension | XAT | XA-compliant database table

The CICS resources are defined in the resource definition file dfhdrdat (with index dfhdrdat.idx). This is an ISAM file.

When Enterprise Server runs the application, it needs to know where the application's dfhdrdat file is. You specify its location using the /ip switch of the casrdtex command and /op switch of the casrdtup command.

Parent topic: Resource Definitions


Exchanging Resource Definitions Between Resource Definition Files

You can import and export resource definitions from and to other resource definition files held on the same or different installations of Enterprise Server.

casrdtup | Imports the resource definition tables in a specified file into the resource definition file dfhdrdat. Use the /ip switch to identify the location of the directory containing dfhdrdat.
casrdtex | Exports the resource definition tables from the resource definition file dfhdrdat to a specified file. Use the /op switch to identify the location of the directory containing dfhdrdat.

Enter casrdtex and casrdtup at the command line to display a full list of the switches available.

Parent topic: Resource Definitions
Related information
casrdtup
casrdtex


Maintaining Resource Definitions

When you have downloaded your resource definitions from the mainframe, they can be maintained in the Windows or UNIX environment. MSS uses several different types of resource, such as programs and files. The standard resources that can be used by most systems are predefined. You need to add definitions only for those resources that are used specifically by your system.

  • Types of Resource
  • Facilities for Maintaining Resources
Parent topic: Resource Definitions


Types of Resource

Each type of resource is defined in a separate table. For example, programs are defined in a processing program table (PPT) and files in a file control table (FCT). For each resource type, more than one table can be defined for the same system. And more than one table for the same resource type can be used by the system, except for the system initialization table (SIT), which defines parameters to control the initialization of the system, and the sign-on table (SNT), which defines user sign-on authorizations.

Note:

Not all programs need entries in the PPT. However PPT entries are required for the following types of program:

  • Programs started by Program Load Tables
  • Programs for autoinstall

They are also required for data tables.

Tables for the same or different resource types can be combined into a group. For example, you will probably find it convenient to combine all the tables for the resources used by an application (or set of related applications) into a single group.

All the groups that you want to be included in the enterprise server startup are defined in a startup list. During startup, MSS uses this list to check that the resources are available and performs appropriate initialization procedures on them.

For full information about CICS resource definition, see the IBM documentation.

Parent topic: Maintaining Resource Definitions


Facilities for Maintaining Resources

You can edit the resource definitions using ESMAC, which provides a graphical user interface. For more information see the section Controlling CICS Resources in the chapter Administering MSS-enabled Enterprise Servers.

Alternatively, you can edit them using a text editor, but to do this, you first need to export the resource definition tables from the dfhdrdat file, and when you have finished editing, you need to import the tables back again. For more information about importing and exporting resources see the section Exchanging Resource Definitions Between Resource Definition Files .

Parent topic: Maintaining Resource Definitions
Related information
Exchanging Resource Definitions Between Resource Definition Files


DEFINE _JOURNAL

Defines the attributes of a journal used for recording system activity within Enterprise Server.
Keyword | Description
_Journal(number) | Specifies the key of a journal record. The key must be a two digit number.
Group(groupname) Names the group the journal definition belongs to. Mandatory.

Groupname can be up to eight characters in length. Acceptable characters are A through Z, a through z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system groups.

Description(text) Describes the sign-on record. Optional.

Text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.

_OPenstate(NEWFILE | APPEND) The status of the journal control table when it is opened. It may contain one of the following values:
  • NEWFILE: a new file will be created
  • APPEND: information will be added at the end of an existing file
_MInreclen(number) | Specifies the minimum logical record length of the file in bytes, in the range 1 through 32767. The value must be less than or equal to the value of _MAxreclen.
_MAxreclen (number) | Specifies the maximum logical record length of the file in bytes, in the range 1 through 32767. The value must be greater than or equal to the value of _MInreclen.
_FILEName | Specifies the name of the physical PC file. Do not include the file extension.
_FILEExt(value) | Specifies the file extension of the physical file.
_FILEShareid(name) | Specifies the Fileshare server on which the file resides. name can be up to 16 characters in length.
_Path(path) | Specifies the path of the physical file. Do not include the filename or the file extension. Mandatory if the file is held on a Fileshare server, in which case _FILEShareid must be present too.
_Rsl(keys) Specifies one or more indicators, each corresponding to one of the 24 resource keys for this journal.

A user has access to a particular resource only through a matching key as defined in his sign-on table entry. To toggle a key on you specify its number here. By default all keys are toggled off. You code the keys as a comma-separated list of individual numbers and ranges separated by hyphens. For example, to toggle the keys 1 to 5 and 10 on, code RSL(1-5,10).

Example

DEFINE _JOURNAL(01) GROUP(TEST)
DESCRIPTION(Journal 1)
       _MINRECLEN(5) _MAXRECLEN(330) _FILENAME(jourfile)
       _FILESHAREID(FSID) _PATH(c:\logging) _FILEEXT(dat)
       _RSL(01,06-09)
Parent topic: CICS Resource Definitions


DEFINE _PGMLIST

Defines a list of programs and the phase in which they are to run. The lists are used at post initialization and shut down.
Keyword | Description
_Pgmlist(name) | Specifies the key of a program list table (PLT) record. Mandatory. Name can be up to two characters in length. Acceptable characters are A through Z, a through z, 0 through 9, $, @ and #.
Group(groupname) | Names the group the program list definition belongs to. Mandatory. Groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system groups.
Description(text) | Describes the program list record. Optional. Text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
_PGMPH(name,phase) | Specifies the name of a program and the phase in which it is to run, separated by a comma. Both parameters are mandatory. Name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a program name starting with DFH, as MSS uses that prefix for system programs. Phase specifies the start up phase in which the program is to be run. It must have a value of 1 or 2. This parameter may be repeated to a maximum of 64 occurrences.

Example

DEFINE _PGMLIST(SD) GROUP(TEST)
DESCRIPTION(Shutdown List)
       _PGMPH(PLTWTO,1) _PGMPH(PLTWTO2,2)
Parent topic: CICS Resource Definitions


DEFINE _SIT

Defines a system initialization table that controls the execution of an Enterprise Server region.
Keyword | Description
_SIT(name) Specifies the key of a system initialization table record. Mandatory. Name can be up to eight characters in length.

Acceptable characters are A through Z, 0 through 9, $, @ and #.

Description(text) Describes the system initialization table record. Optional.

Text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.

_ CWasize (value) | Specifies the size of the region's common work area (CWA) in bytes in the range 0 through 32767. This area is shared among applications running in the region.
_COMmareaovr(value) Specifies the minimum amount of storage to be allocated to the communications area (COMMAREA) to allow MSS to behave like mainframe CICS.

The size is in the range 0 through 32767. The effect of this is that when a program is passed a COMMAREA smaller than the COMMAREA defined in the program, the passed COMMAREA is automatically extended in length to fill the defined space.

_SHAredpages(value) | Specifies the number of shared pages in memory to be reserved for all the processes that run in the region. Each page is 4 KB long.
_SERvers(value) | Specifies the number of service execution processes that are to be started at server initialization.
_TRTsize(2 | 14-9999) Specifies 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 Auxiliary Trace is active.

A value of 2 means that there is space for only one entry, and if Auxiliary Trace is active each entry is written straight out to disk.

_SYSid(sysid) | Specifies the system ID of the region. This is the name by which it is known to other regions.
_INITIaltran(tranid) | Specifies the ID of an initial transaction that runs on every terminal when it logs on to the region.
_PLTPilist(name) | Specifies a program list table (PLT) entry that nominates the initialization programs to be run when the region is started.
_PLTSdlist (name) | Specifies a program list table (PLT) entry that nominates the shutdown programs to be run when the region is stopped.
_STArtuplist(name) Specifies the startup list which determines the resources to be loaded when the server is initialized.

Default value is DFHLIST.

_RETrievecmd(string) Specifies the character string that BMS control is to interpret as the BMS paging command RETRIEVE.

Default value is P/.

_CHAincmd(string) Specifies the character string that BMS control is to interpret as the BMS paging command CHAIN.

Default value is C/.

_PURgecmd (string) Specifies the character string that BMS control is to interpret as the BMS paging command PURGE.

Default value is D/.

_COPycmd (string) Specifies the character string that BMS control is to interpret as the BMS paging command COPY.

Default value is T/.

_PF1Cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF1 key.
_PF2Cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF2 key.
_PF3Cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF3 key.
_PF4Cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF4 key.
_PF5Cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF5 key.
_PF6Cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF6 key.
_PF7Cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF7 key.
_PF8Cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF8 key.
_PF9Cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF9 key.
_PF10cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF10 key.
_PF11cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF11 key.
_PF12cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF12 key.
_PF13cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF13 key.
_PF14cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF14 key.
_PF15cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF15 key.
_PF16cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF16 key.
_PF17cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF17 key.
_PF18cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF18 key.
_PF19cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF19 key.
_PF20cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF20 key.
_PF21cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF21 key.
_PF22cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF22 key.
_PF23cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF23 key.
_PF24cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF24 key.
_PA1cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PA1 key.
_PA2cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PA2 key.
_PA3cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PA3 key.
_ABEnddump(NO | YES) Indicates that MSS should produce a dump if an abend occurs in any of your transaction programs.

Default is NO.

_DATEFormat(MMDDYY | DDMMYY | YYMMDD) Specifies the display format used to display the date. This is used in conjunction with the FULLDATE (for four-digit years) or DATE (for two-digit years) operands of the EXEC CICS FORMATTIME command. This setting determines only the order of day, month, and year; it does not prevent four digits from being displayed.

Default is MMDDYY

_DATESep(value) Specifies the character to be used to separate the day, month and year components of the date. You can specify any displayable character.

Default is solidus (/).

_TIMEsep(value) Specifies the character to be used to separate the hours, minutes and seconds components of the time. You can specify any displayable character.

Default is colon (:).

_NRECTSPath(path) | Specifies the path for non-recoverable temporary storage queues.
_RECTSPath (path) | Specifies the path for recoverable temporary storage queues.
_NRECTDPath (path) | Specifies the path for non-recoverable transient data queues.
_RECTDPath (path) | Specifies the path for recoverable transient data queues.
_NRECTSFshr(name) | Specifies a Fileshare server ID for non-recoverable temporary storage queues.
_RECTSFshr (name) | Specifies a Fileshare server ID for recoverable temporary storage queues.
_NRECTDFshr (name) | Specifies a Fileshare server ID for non-recoverable transient data queues.
_RECTDFshr (name) | Specifies a Fileshare server ID for recoverable transient data queues.
_PRINTSupp(NO | YES) Indicates whether or not the region supports a printer:
  • YES: the region supports a printer
  • NO: the region does not support a printer (default)
_PRINTDest(name) | Specifies the printer destination, up to 14 characters in length. You must also specify 3270 printer support when specifying a printer destination.
_FILeshare(NO | YES) Indicates whether MSS should create a dedicated Fileshare server process as part of region startup.

Default is NO.

_FSHRUserid(user) Specifies the user ID to be used by the region to log on to all Fileshare servers that MSS is configured to use. You should specify a user ID only if Fileshare security is enabled. If you specify a user ID, you must also specify a password in _FSHRPASSWD. The user ID and password combination must correspond to an entry in the password file of each Fileshare server the region is to access.

The ID may be up to 20 characters.

_FSHRPasswd(password) | Specifies the 20-character password used in conjunction with _FSHRUSERID to log on to all Fileshare servers that MSS is configured to use.
_TSColdstart(NO | YES) Indicates whether or not MSS should reset temporary storage queues at region start up.

Default is NO.

_TDColdstart(NO | YES) Indicates whether or not MSS should reset transient data queues at region start up.

Default is NO.

_AUXtrace(NO | YES) Indicates whether MSS is to enable or disable auxiliary tracing.

Default is NO.

_TRACEStore(NO | YES) Indicates whether MSS is to enable or disable storage control tracing.

Default is NO.

_TRACETASk(NO | YES) Indicates whether MSS is to enable or disable task control tracing.

Default is NO.

_TRACEFile(NO | YES) Indicates whether MSS is to enable or disable file control tracing.

Default is NO.

_TRACEDump(NO | YES) Indicates whether MSS is to enable or disable dump control tracing.

Default is NO.

_TRACETStd(NO | YES) Indicates whether MSS is to enable or disable temporary storage/transient data tracing.

Default is NO.

_TRACEIntrvl(NO | YES) Indicates whether MSS is to enable or disable interval control tracing.

Default is NO.

_TRACEJournl(NO | YES) Indicates whether MSS is to enable or disable journal control tracing.

Default is NO.

_TRACETABle(NO | YES) Indicates whether MSS is to enable or disable table management tracing.

Default is NO.

_TRACEUSer(NO | YES) Indicates whether MSS is to enable or disable user tracing .

Default is NO.

_TRACETErm(NO | YES) Indicates whether MSS is to enable or disable terminal control tracing.

Default is NO.

_TRACECOmms(NO | YES) Indicates whether MSS is to enable or disable communications tracing.

Default is NO.

_TRACEMessg(NO | YES) Indicates whether MSS is to enable or disable message tracing.

Default is NO.

_TRACECCi(NO | YES) Indicates whether MSS is to enable or disable CCI tracing.

Default is NO.

_TRACEAPi(NO | YES) Indicates whether MSS is to enable or disable CICS API tracing.

Default is NO.

_TRACEUExit(NO | YES) Indicates whether MSS is to enable or disable user exit tracing.

Default is NO.

_ENAbtn3270(NO | YES) Indicates whether TN3270 is enabled or not.

Default is NO.

_TN3270port(23 | value) Specifies the port number on which MSS listens for TN3270 requests.

Default value is 23.

_EXTernshut(ALLOWED | LOGON | NONE) Specifies the type of external shutdown.You can choose from:
  • ALLOWED: no special privileges are required (default).
  • LOGON: a successful logon must be made first.
  • NONE: external shutdown is disallowed.
Note: An external shutdown is a shutdown of the server initiated by clicking Shutdown on the Control page, Stop Server on the Enterprise Server Administration Server Details page, or issuing a casstop command.
_SECuritykey(0- 64) Specifies a security key number. MSS checks this against the shutdown security key specified when you shut down the region. You need to specify a security key number only if you choose LOGON in External Shutdown.

Default value is 64.

_STGcushion(0-262144) Specifies 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.

Default value is 4096

_DUMponsysab(NO | YES) Indicates whether MSS should produce a dump if an abend occurs in its own code.

Default is NO.

_WAItonsend(NO | YES) Indicates whether MSS should wait on each terminal control or BMS SEND operation until it receives a response.
  • YES: MSS does not wait on each SEND, thus enabling terminal control and send operations to be buffered, which improves performance (default)
  • NO: MSS does wait
_TDDEFREQD(NO | YES) Indicates whether a transaction program executing in this region can create a transient data queue only if it has been defined in the destination control table (DCT). Applies only to intra-partition transient data queues.
  • YES: a DCT entry must be defined
  • NO: a DCT entry is optional (default)
_DEVelopment | Obsolete.
_DEFerpct(NO | YES | 1-64) Specifies the number of PCT groups whose loading you want to defer.
  • YES: none of the PCT entries is loaded into memory when the region starts up.
  • NO: all PCT entries are loaded into memory when the region starts up (default).
  • any other value: the PCT entries in that number of groups are not loaded into memory when the region starts up. For example, if you specify 3, the last three groups in the start up list's precedence order are not loaded into memory when the region starts up.
I
_MAXauxdump(value) | Specifies the maximum size of the auxiliary trace and dump file in kilobytes. A value of 0 (zero) means that there is no maximum size.
_FORceprog(NO | YES) Indicates whether MSS should reload programs each time they are invoked.
  • YES: programs are loaded on each invocation.
  • NO: programs are reused (default)
This applies only to programs that are not marked resident and have not been loaded with the hold attribute.
_TERmorigsys(NO | YES) Indicates how a remote CICS region handles a START request shipped to it by this CICS region, and the terminal that should be started is not defined on the remote system:
  • YES: the remote region should assume that the terminal is defined on the originating system and should start a terminal anyway
  • NO: the remote system returns a TERMIDERR to the originating region (default)
_COLdstartrc(NO | YES) Indicates whether the auxiliary trace and dump files are to be deleted at region startup:
  • YES: the trace and dump files are deleted
  • NO: the trace and dump files are reused (default)
_CICsrel | Obsolete.
_LOcaltrtsz(value) Specifies 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.

_UNICLIGway(NO | YES) Indicates whether an IBM Universal Clients gateway is to be established when the region starts up:
  • YES: a gateway is established at startup
  • NO: a gateway is not established at startup (default)
_UNICLIPort(value) Specifies the TCP/IP port number to use for the Universal Clients gateway.

This must match the TCP/IP port number you specify in the Universal Clients configuration file except that if you use the defaults, the value in the configuration file is 0 whereas the default value for _UNICLIPort is 1435.

_UNICLISess(0-255) | Specifies the number of sessions you want allocated to servicing inbound requests per connection, where connection corresponds to a client machine.
_MQENABCOnn(NO | YES)
Note: This field is now deprecated. Define the queue manager name on the MQ Listener tab.
Indicates whether support for IBM WebSphere MQ® is enabled:
  • YES: WebSphere MQ support is enabled
  • NO: WebSphere MQ support is disabled (default)
_MQENABCKti(NO | YES)
Note: This field is now deprecated. Define the queue manager name on the MQ Listener tab.
Indicates whether support is enabled for the transaction CKTI, which monitors the IBM WebSphere MQ® initiation queue:
  • YES: CKTI support is enabled
  • NO: CKTI support is disabled (default)
_MQQmgrname(name)
Note: This field is now deprecated. Define the queue manager name on the MQ Listener tab.

Specifies the name of the IBM WebSphere MQ® queue manager. Can be up to 48 characters.

_MQInitqname(name)
Note: This field is now deprecated. Define the queue manager name on the MQ Listener tab.

Specifies the name of the IBM WebSphere MQ® initiation queue. Can be up to 48 characters.

_AUToinsexit(name) Specifies the name of the program to be used to autoinstall terminals. Specify:
  • DFHZATDX - the autoinstall program supplied with MSS.
  • User-specified: the name of your autoinstall exit program. Up to 8 characters from 0 through 9, A through Z, @, # and $. The first character must not be numeric.
_TRAnsthold(-1 | 0-65535) | Specifies the amount of time in seconds that a transaction is allowed to execute before it is abended.
_DTImeout(0-4080) Specifies the maximum time in seconds that the region will permit an application to wait for a resource that has been locked by another process. A value of 0 indicates that there is no timeout.
Note: In CAS you can override this value at runtime by changing the Deadlock Timeout on the ESMAC Control screen. You can also override this value for an individual transaction through the relevant Program Control Table entry.
_RTImeout(0-4080) Specifies the maximum time in seconds allowed for operator response to an explicit CICS RECEIVE command before the transaction is abended.
A value of 0 indicates that there is no timeout.
Note: In CAS you can override this value at runtime by changing the Input Timeout on the ESMAC Control screen. You can also override this value for an individual transaction through the relevant Program Control Table entry.
_RUNaway(0-2700) Specifies the maximum continuous period of time in seconds that the region will allow a transaction to run without making a CICS, EZASOKET or WebSphere MQ API call. When this time is exceeded, the transaction is abended.
A value of 0 indicates that there is no timeout.
Note: In CAS you can override this value at runtime by changing the Runaway Timeout on the ESMAC Control screen. You can also override this value for an individual transaction through the relevant Program Control Table entry.
_IDTimeout(0-4080) Specify the time in minutes that the system will allow an ESMAC or TN3270 client session to remain idle before logging off the user. A value of 0 indicates that there is no timeout.
Note: In CAS you can override this value at runtime by changing the ID Timeout on the ESMAC Control screen.

Example

DEFINE _SIT(TESTSIT)
DESCRIPTION(Sample SIT)
       _CWASIZE(512) _COMMAREAOVR(0) _SHAREDPAGES(128) _SERVERS(2)
       _TRTSIZE(341) _SYSID($MCO) _INITIALTRAN(CESN)
       _STARTUPLIST(MCOSUPL) _RETRIEVECMD(P/) _CHAINCMD(C/)
       _PURGECMD(D/) _COPYCMD(T/) _ABENDDUMP(NO) _DATEFORMAT(MMDDYY)
       _DATESEP(/) _TIMESEP(:) _PRINTSUPP(NO) _CCIGATEWAY(NO)
       _TSCOLDSTART(NO) _TDCOLDSTART(NO) _TRACESTORE(NO) _TRACETASK(NO)
       _TRACEFILE(NO) _TRACEDUMP(NO) _TRACETSTD(NO) _TRACEINTRVL(NO)
       _TRACEJOURNL(NO) _TRACETABLE(NO) _TRACEUSER(NO) _TRACETERM(NO)
       _TRACECOMMS(NO) _AUXTRACE(NO) _TRACEMESSG(NO) _TRACECCI(NO)
       _TRACEAPI(NO) _TRACEUEXIT(NO) _CCIDDE(NO) _CCIIPX(NO)
       _CCINAMEP(NO) _CCINETBIOS(NO) _CCITCPIP(NO) _ENABTN3270(NO)
       _EXTERNSHUT(ALLOWED) _SECURITYKEY(64) _STGCUSHION(1)
       _DUMPONSYSAB(YES) _WAITONSEND(YES) _TDDEFREQD(NO)
       _DEVELOPMENT(YES) _DEFERPCT(NO) _MAXAUXDUMP(0) _FORCEPROG(YES)
       _TERMORIGSYS(NO) _TN3270PORT(0) _CICSREL(33) _FILESHARE(NO)
       _LOCALTRTSZ(341) _UNICLIGWAY(NO) _MQENABCONN(NO) _MQENABCKTI(NO)
       _TCPIPGWPORT(0) _TRANSTHOLD(0) _DTIMEOUT(0) _RUNAWAY(0)
       _RTIMEOUT(0) _IDTIMEOUT(0)
Parent topic: CICS Resource Definitions


DEFINE _STARTUPLIST

Defines a list of resource groups to be installed at system initialization.
Keyword | Description
_STARTUPLIST (name) | Specifies the key of a startup list record. Mandatory. Name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #.
_GRP(groupname) | Names the group to be in the startup list. Groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. This parameter may be repeated for as many groups as there are in the list.

Example

DEFINE _STARTUPLIST(TESTLIST)
DESCRIPTION(Example Startup List)
       _GRP(DFHBMS) _GRP(DFHCONS) _GRP(DFHEDF) _GRP(DFHHARDC)
       _GRP(DFHISC) _GRP(DFHOPER) _GRP(DFHSIGN) _GRP(DFHSPI)
       _GRP(DFHTYPE) _GRP(DFHVTAM) _GRP(DFH$ACCT) _GRP(DFH$IVP)
       _GRP(DFHTERM) _GRP(PEH) _GRP(TEST)
Parent topic: CICS Resource Definitions


DEFINE _TEMPSTORAGE

Defines the attributes of a temporary storage (TS) record set.
Keyword | Description
_Tempstorage(name) Specifies the key of a temporary storage (TS) record. Mandatory.

Name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #.

Group(groupname) Names the group the temporary storage definition belongs to. Mandatory.

Groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system groups.

Description(text) Describes the temporary storage record. Optional.

Text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.

_REMOTESysid (sysid) Applicable only for remote queues. Specifies the ID of the remote system that holds the queue. This must correspond to either:
  • The Local SYSID field in the SIT used to run the related remote CICS region.
  • The APPLID of another CICS system.
_REMOTEName(name) | Applicable only for remote queues. Names the remote queue. Necessary only if it differs from the local queue name.
_RECovery (NO | YES) Indicates whether or not the queue is recoverable.

Default is NO.

_RSl (RSL stands for Resource Security Level.) Specifies one or more indicators, each corresponding to one of the 24 resource keys for this program.

A user has access to a particular resource only through a matching key as defined in his sign-on table entry. To toggle a key on you specify its number here. By default all keys are toggled off. You code the keys as a comma-separated list of individual numbers and ranges separated by hyphens. For example, to toggle the keys 1 to 5 and 10 on, code RSL(1-5,10).

Example

DEFINE _TEMPSTORAGE(TESTQ9) GROUP(TEST)
DESCRIPTION(Sample TSQ)
       _REMOTESYSID(SYSB) _REMOTENAME(RMT) _RECOVERY(YES)
       _RSL(01-03,06,14)
Parent topic: CICS Resource Definitions


DEFINE _XOPENCOMPAT

Defines the attributes of XA compatible resources (external resource managers).
Keyword | Description
_Xopencompat(name) Specifies the key of an X/Open or XA resource manager record. Mandatory.

Name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #.

Group(groupname) Names the group the XA definition belongs to. Mandatory.

Groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system groups.

Description(text) Describes the XA record. Optional.

Text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.

_Openstring (string) Specifies 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.

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. Use of open and close strings is mutually exclusive with DATABASE, USERID and PASSWORD.

Note: The contents of this string are database-specific. For DB2, the contents are documented in IBM's DB2 Administration Guide and Application Programmer's Guide. For Oracle, see the Oracle Application Developer's Guide - Fundamentals.
_Closestring(string) | Specifies 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.
_Database(name) | Specifies the name by which the resource manager is known.
_Userid(user) | Specifies a resource manager ID, which is used internally to identify a particular XA configuration. This must be unique within the system.
_Password(password) | Specifies the password required for the User ID.
_SWitchmod(path) | Specifies the location of the executable file (DLL) that contains the entry point that returns the xa_switch_t structure to the system.
_Runtime(None | Db2 | Oracle | Sybase | User) Specifies an external resource manager that the server needs to communicate with on behalf of container-managed applications.

Default is None.

_SUpportmod(name) | If you specified USER in RUNTIME, specify the name of the module that supplies the run-time support for the database calls made by the application.

Example

Example
DEFINE _XOPENCOMPAT(ORACLE) GROUP(TEST)
DESCRIPTION(Oracle XA Sample)
       _OPENSTRING(Oracle_XA+Acc=P/scott/tiger+SesTm=0+DbgFl=15)
       _SWITCHMOD(c:\oracle\bin) _RUNTIME(ORACLE) _SUPPORTMOD(xaosw)
Parent topic: CICS Resource Definitions


DEFINE JES

Defines a JES/IMS initiator or a JES printer.
Keyword | Description
JES(name) | Specifies the key of a JES/IMS initiator or printer resource record. Mandatory. Name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #.
Group(groupname) | Names the group the JES definition belongs to. Mandatory. Groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support uses that prefix for system groups
Description(text) | Describes the initiator/printer record. Optional. Text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
Type(Initiator|Printer) | Specifies whether the record defines an initiator or a printer.
Classes(string) | Specifies the classes to be associated with this initiator or printer. Each class must be defined individually, and must be composed of characters A through Z, and 0 through 9. For example, to define classes A and B: CLASSES(AB)
PRintername(name) | Specifies the name by which the printer is known. Valid only for TYPE(PRINTER).
EXitmodule(name) | Specifies an exit module to be invoked before a record is to be printed. Valid only for TYPE(PRINTER).

Examples

DEFINE JES(TESTINIT) GROUP(TEST)
DESCRIPTION(INITIATOR FOR CLASSES A-D and 0)
       TYPE(INITIATOR) CLASSES(ABCD0)
DEFINE JES(TESTPRNT) GROUP(TEST)
DESCRIPTION(PRINTER FOR CLASS X)
       TYPE(PRINTER) CLASSES(X)
       PRINTERNAME(testprinter)
Parent topic: CICS Resource Definitions


Configuring CICS for Security

This chapter describes the basic security features that you can implement with MSS. It explains:
  • The security features provided by MSS
  • How to enable transaction and resource security
  • Password encryption and decryption

You can implement more extensive security through the use of the Enterprise Server External Security Facility. For details see Introduction to Enterprise Server Security.

  • Overview
  • Transaction Security
  • Resource Security
  • Sign-on Table (SNT) Entries
  • Password Encryption and Decryption
Parent topic: CICS Support
Related information
Introduction to Enterprise Server Security


Overview

MSS provides optional security for individual transactions and resources. It is off by default.

MSS controls access to transactions and resources through three mechanisms:

  • Transaction security
  • Resource security
  • Sign-on Table (SNT) entries

MSS also provides a mechanism for implementing your own password encryption and decryption strategy.

Parent topic: Configuring CICS for Security


Transaction Security

Transaction security allows you to control access to individual transactions.

To enable security for a transaction, you must do two things:

  • Define a set of security keys for the transaction in its PCT entry. Each security key is a number in the range 1 through 64.
  • Specify a set of security keys in a user's SNT entry. A user can access a transaction if at least one of the transaction's security keys matches a security key specified in that user's SNT entry.

If you assign security key number 1 to a transaction, any user can run the transaction; all users own security key 1 by default. Figure 9-1 illustrates security key checking applied to a transaction.

Figure 1. Transaction key checking
Transaction key checking
Parent topic: Configuring CICS for Security


Resource Security

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, 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: Configuring CICS for Security


Sign-on Table (SNT) Entries

You must create an entry for the user in the Sign-on Table (SNT) if the user requires:

  • A user ID and password. These are required if:
    • The user has to sign on to MSS using the supplied transaction CESN.
    • The user wants to modify resource definitions using the Resource Definition Facility if security is enabled.
  • Security keys and/or resource keys.

Each entry in the SNT specifies the following:

  • The ID with which a user signs on through the CESN transaction.
  • The user's MSS password.
  • The user's security and resource keys.
  • The User SYSAD
Parent topic: Configuring CICS for Security


The User SYSAD

When you create a MSS Resource Definition File, its SNT already contains an entry for the system administrator, with username SYSAD and password SYSAD. (You must enter this password in upper case.)

User SYSAD has system administrator privileges and owns all security and resource keys.

You should change SYSAD's password to something more secure as soon as possible.

Parent topic: Sign-on Table (SNT) Entries


Password Encryption and Decryption

MSS calls a user-replaceable module, dfhucryp.dll, located in both \bin and \bin64, to perform encryption and decryption of user passwords. The installed module does not actually perform any encryption; that is, the encrypted password is the same as the unencrypted password. You can replace this module with one that implements a password encryption and decryption strategy appropriate for your site.

The example module, dfhucry1.dll, that implements a simple encryption and decryption scheme, is supplied. The source (.cbl) form is provided in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin. It uses the number of 1 bits in the user ID as a shift count and a pair of encipher and decipher tables.

  • The Interface to the Password Module
  • Choosing an Encryption and Decryption Scheme
  • Replacing the Password Encryption and Decryption Scheme
Parent topic: Configuring CICS for Security


The Interface to the Password Module

The interface to dfhucryp.gnt is a standard call interface, requiring a single parameter:

CALL "DFHUCRYP" USING CRYPT-PARAMETER-AREA.
 01  CRYPT-PARAMETER-AREA.
     05  CRYPT-FUNCTION                PIC XX COMP-X.
         88  CRYPT-ENCRYPT-88             VALUE 1.
         88  CRYPT-DECRYPT-88             VALUE 2.
     05  CRYPT-RESULT                  PIC XX COMP-X.
         88 CRYPT-SUCCESSFUL-88           VALUE 0.
         88 CRYPT-FAILED-88               VALUE 1.
     05  CRYPT-USER-ID                 PIC XX(8).
     05  CRYPT-ENCRYPTED-PASSWORD      PIC XX(8).
     05  CRYPT-DECRYPTED-PASSWORD      PIC XX(8).

where:

CRYPT-FUNCTION Specifies the function as encrypt (=1) or decrypt (=2).

The encrypt function takes the decrypted password as input and outputs the encrypted password, possibly referring to the user ID field.

The decrypt function takes the encrypted password as input and outputs the decrypted password, possibly referring to the user ID field.

CRYPT-RESULT | This field is used to signal the success (=0) or failure (=1) of the function. Since a failure is treated as a password mismatch in all validation functions, the error return can be used to screen out unacceptable passwords during the SNT update process.
CRYPT-USER-ID | The user ID associated with the password being encrypted or decrypted.
CRYPT-ENCRYPTED-PASSWORD | The encrypted password. This field is used as an input field by the decrypt function and as an output field by the encrypt function.
CRYPT-DECRYPTED-PASSWORD | The decrypted password. This field is used as an output field by the decrypt function and as an input field by the encrypt function.
Parent topic: Password Encryption and Decryption


Choosing an Encryption and Decryption Scheme

The only restrictions on the encryption and decryption scheme you choose are as follows:

  • It must be a reversible encryption scheme.
  • The implementation must conform to the interface described in the previous section.

You should bear in mind that the routine is called on entry to the resource definition maintenance functions and at every attempt to sign on to MSS. A slow scheme can, therefore, result in poor performance.

Parent topic: Password Encryption and Decryption


Replacing the Password Encryption and Decryption Scheme

If you alter your password encryption and decryption scheme, any encrypted passwords stored in the Sign-on Table (SNT) must be decrypted using the old scheme and then re-encrypted with the new scheme. A utility program called dfhpcryp.gnt is supplied to assist in this conversion.

The procedure for moving to a new encryption scheme is described below. In this procedure, you introduce your new encryption module to the system as dfhucryu.gnt. You then run the dfhpcryp.gnt utility, which uses the existing module (dfhucryp.gnt) and your new one to perform the conversion. When the conversion is complete, you replace the existing module with your new one.

Before you make any changes, take a backup copy of the following:

  • The Resource Definition File (dfhdrdat and dfhdrdat.idx). This holds the SNT entries.
  • The current encryption module (dfhucryp.gnt).

To run dfhpcryp.gnt:

  1. Compile the new encryption module to .gnt.
    Note:

    Do not replace the existing dfhucryp.gnt at this stage. Your new module must only replace the existing dfhucryp.gnt after you have run the dfhpcryp.gnt utility to perform the conversion.

  2. Rename your new encryption module to dfhucryu.gnt and copy it into the same directory as the existing dfhucryp.gnt.
  3. Ensure that no part of MSS is active.
  4. Run the dfhpcryp.gnt utility.
  5. When dfhpcryp.gnt completes, remove dfhucryp.gnt and rename dfhucryu.gnt to dfhucryp.gnt.
  6. Back up the modified Resource Definition File.

MSS is now ready to run with the new encryption and decryption scheme.

The backups taken during this process are important in case you want to return to the old encryption and decryption scheme for any reason.

Parent topic: Password Encryption and Decryption


Configuring CICS for Databases

MSS CICS provides support for both relational and hierarchical databases. This chapter discusses the support provided.

  • Database Managers Supported
  • Using Other Database Managers
Parent topic: CICS Support


Database Managers Supported

MSS provides built-in support for the same XA-compliant database managers as Enterprise Server without MSS.

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.

You can configure the database managers using either the Edit Server page in Enterprise Server Administration, or the CICS XAT page in ESMAC.

The support for relational database managers enables CICS applications to issue database DDL and DML statements in the form of embedded Structured Query Language. SQL requests are structured in a similar way to CICS commands. Using them, you can create, modify and query data tables.

  • To define an XA resource (XAR) for an enterprise server region
  • To create a resource table
Parent topic: Configuring CICS for Databases
Related information
To add an XA resource to an enterprise server
To create a resource table
Configuring Resource Managers


Using Other Database Managers

You can access other, non-XA-compliant databases through . The recommended method is to use the exit program DFHUSYNC. A sample exit program is supplied as dfhusync.cbl, located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin. Follow these steps to customize the sample exit program:

  1. Add code to be invoked at any or all of the following points:

    • SEP initialization

    • The start of a CICS task

    • When rollback is required

    • When a prepare is required for a syncpoint

    • When a commit is required

    • SEP shutdown

      This code should invoke the appropriate actions from the database manager being used. If you want to enable commit and rollback processing (two-phase commit), include the SQL Communications Area (SQLCA) in the Working-Storage Section of the dfhusync.cbl module.

  2. Run dfhusync.cbl through the appropriate SQL preprocessor.

  3. In Enterprise Developer, compile dfhusync.cbl to any callable format. Do not use the CICS preprocessor.

  4. Put the compiled module in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin, or, if Enterprise Server is installed standalone, %ProgramFiles(x86)%\Micro Focus\Enterprise Server\bin. This replaces the default file supplied with MSS.

Note: A CICS application that updates more than one single-phase resource compromises resource integrity
Parent topic: Configuring CICS for Databases


Intersystem Communication

This chapter describes the facilities provided by MSS for Intersystem Communication and how to set up MSS to use these facilities.

  • Overview
  • Common Configuration Tasks
  • Function Shipping
  • Asynchronous Processing
  • Transaction Routing
  • Distributed Program Linking
  • Distributed Transaction Processing
  • Network Links
Parent topic: CICS Support


Overview

Intersystem Communication (ISC) provides communications between two MSS systems, or between a CICS systemand MSS, or between a CICS system or MSS and an IBM-compatible CICS system using Mainframe Access. It enables distributed processing, where the processing of CICS transactions is split between various systems.

You need to do some configuration to get these facilities working. Some of this is common to all distributed processing facilities, while some is specific to one facility.

Parent topic: Intersystem Communication


Common Configuration Tasks

To enable any of the distributed processing facilities, you need to do the following:

  • For both outbound and inbound flows, define network links between the MSS system and the system or systems that you want to communicate with. For each remote system you define a connection.
  • For both outbound and inbound flows add a listener for Intersystem Communication to the enterprise server. This must be of type "MTO ISC", have the name "MF MTO Inter-System Communication" and have Legacy Micro Focus Application Format checked.
  • For inbound flows, add the resource group DFHISC to the startup list for the SIT. (You do not need to do this for distributed transaction processing (DTP)).
  • To Add a Service Listener to an Enterprise Server Instance
Parent topic: Intersystem Communication
Related information
To add a service listener to an enterprise server
Network Links


Function Shipping

Function shipping enables a transaction executing on a local MSS system to access remote resources (files, temporary storage queues and transient data queues).

The operation of function shipping is illustrated below.

Figure 1. Function Shipping
Function Shipping

Outbound function shipping is what happens when your local transaction programs ship functions to remote MSS systems or to IBM-compatible CICS systems.

Inbound function shipping is what happens when remote MSS systems ship functions to your MSS system.

  • Restrictions on Function Shipping
  • Configuration for Function Shipping
Parent topic: Intersystem Communication


Restrictions on Function Shipping

The following restrictions apply to function shipping as implemented in MSS:

  • You cannot ship a function directly to a DL/I (IMS) database.
  • You should not ship a function that updates a resource across multiple links, because recovery cannot be coordinated.
  • You should take syncpoints from your system and not the invoked end of the link, otherwise you might get unpredictable results.

    This is advisable because function shipping only incorporates sync level 1 logic. Whether you have single or multiple connected systems, a sync request can be propagated through all the connected systems.

Parent topic: Function Shipping


Configuration for Function Shipping

This section describes any configuration required that is specific to function shipping. See the section Common Configuration Tasks for configuration that is required for all types of intersystem communication.

You might need to do some specific configuration for outbound function shipping. There are two ways of ensuring that functions get shipped to a remote system:

  • Specify the system ID of the remote system in the relevant EXEC CICS command. For example:
    EXEC CICS READ FILE(CUSTFILE) SYSID(HS01)

    reads the file CUSTFILE which belongs to the remote system HS01.

    EXEC CICS WRITEQ TD QUEUE(QUEUE01) SYSID(HS01)

    writes to the transient-data queue QUEUE01 which belongs to the remote system HS01.

  • Specify the system ID and name of the resource in the resource's local definition. The following table shows the fields that need updating:

    Table Required Entry
    FCT The file to be accessed, specifying:
    Remote SYSID on the FCT Details page of ESMAC
    The ID of the SysC table entry for the remote system
    Remote File on the FCT Details page of ESMAC
    The name by which the file is known on the remote system. If you do not specify this field, the file is assumed to have the same name on both systems
    DCT The TD queue that can be accessed by local transactions, specifying:
    SYSID on the DCT Details page of ESMAC
    The ID of the SysC table entry for the remote system
    Name on the DCT Details page of ESMAC
    The name by which the TD queue is known on the remote system. If you do not specify this field, the TD queue is assumed to have the same name on both systems.
    TST The remote TS queue that can be accessed by local transactions, specifying:
    SYSID on the TST Details page of ESMAC
    The ID of the SysC table entry for the remote system
    Name on the TST Details page of ESMAC
    The name by which the TS queue is known on the remote system. If you do not specify this field, the TS queue is assumed to have the same name on both systems
Note: If local transactions using ANSI ship functions to an IBM-compatible EBCDIC CICS system, you must set up data conversion facilities on the remote system.
Parent topic: Function Shipping
Related information
Common Configuration Tasks


Asynchronous Processing

Asynchronous processing enables a local transaction program to initiate a transaction program on a remote system by means of the EXEC CICS START command. The remote transaction does not attempt to send a response back to the initiating local transaction program; this is what makes it asynchronous.

There are two ways of doing outbound asynchronous processing with MSS:

  • Specify in a transaction definition (PCT) that it is remote.
  • Name the system ID of the remote system in the EXEC CICS START command, which provides automatic transaction initiation (ATI).

If you use the first way, you need to do some specific configuration by defining the fields in the PCT as follows:

Required Entry

Each remote transaction that can be initiated (using ATI) by a local transaction, specifying:

Remote SYSID on the PCT Details page of ESMAC
The ID of the SysC table entry for the remote system
Remote PCT on the PCT Details page of ESMAC
The name by which the transaction is known on the remote system. If you do not specify this field, the transaction is assumed to have the same name on both systems

No specific configuration is required for inbound asynchronous processing.

Parent topic: Intersystem Communication
Related information
Common Configuration Tasks


Transaction Routing

Transaction routing enables an MSS system to invoke transactions on a remote system. The terminal attached to the local system is treated as if it were attached to the remote system.

The operation of transaction routing is illustrated below.

Figure 1. Transaction Routing
Transaction Routing
  • Implementing Transaction Routing
  • Restrictions on Transaction Routing
  • Configuration for Transaction Routing
Parent topic: Intersystem Communication


Implementing Transaction Routing

You can implement transaction routing in MSS in either of two ways:

  • Specify that particular transactions are to be routed to a remote system. See the section Configuration for Transaction Routing later in this chapter for more information on how to set up this implementation of transaction routing.
  • Use the supplied transaction CRTE to create a routing session on a remote system.
  • Using the Routing Transaction CRTE
  • Defining Remote Terminals
Parent topic: Transaction Routing
Related information
Configuration for Transaction Routing


Using the Routing Transaction CRTE

You can use the supplied transaction CRTE to start a routing session on a remote system. When the routing session has been established, your local system appears as a remote terminal to the remote system. All transactions invoked during this session are executed on the remote system.

The use of CRTE to implement transaction routing is illustrated below.

Figure 1. Transaction Routing via CRTE
Transaction Routing via CRTE

No configuration of the local or remote system (other than the link itself) is required when using CRTE. You should use CRTE, instead of making PCT definitions, in the following cases:

  • For infrequently-invoked transactions.
  • For transactions that reside on all of your systems.

Note that, because the routing session has to be explicitly established and canceled, you might have to perform additional signon operations.

If the user does not sign on, the surrogate terminal created is associated with the AOR default user. When a transaction is run, the security checks are carried out against this default user.

If the user does sign on, using the CESN transaction while running CRTE, the surrogate points to the userid of the signed-on user.

CRTE supports both conversational and pseudo-conversational transactions. Transactions invoked by PA or PF keys cannot be invoked through CRTE.

Parent topic: Implementing Transaction Routing


Defining Remote Terminals

The remote system needs a definition of the terminal from which the transaction is issued. You can either:

  • Define the terminal in the remote system as well as the local system. This method is known as duplicating a terminal definition.
  • Ship the local definition to the remote system when a transaction is routed to the remote system. This method is known as shipping a terminal definition.

3270 terminals and printers default to the shipping method, but you can duplicate the definitions if you choose.

With either method, each terminal name must be unique across the entire network.

Shipping definitions has some advantages over duplicating definitions:

  • You can save on the use and maintenance of disk storage on the remote system because the remote terminal definitions are not stored there.
  • You also save the initial labor of entering the remote definitions on the remote system.
Parent topic: Implementing Transaction Routing


Restrictions on Transaction Routing

There are several restrictions that apply to the transaction routing as implemented in MSS:

  • BMS paging is not supported.
  • The fully-qualified network name might not be available in the IBM mainframe monitoring record of an APPC link.
  • You should not invoke a transaction on a remote mainframe CICS system that uses the MSGINTEG(YES) or PROTECT(YES) options, as they cannot be honored on sync level 1 links.
Parent topic: Transaction Routing


Configuration for Transaction Routing

This section describes any configuration required that is specific to transaction routing. See the section Common Configuration Tasks for configuration that is required for all types of intersystem communication.

You might need to do some specific configuration for outbound transaction routing. There are two ways of ensuring that transactions get routed to a remote system:

  • Specify the transaction that you want to route and the system ID of the remote system in an EXEC CICS START command. For example:
    EXEC CICS START TRANSID(CWEN)SYSID(HS01)

    starts the transaction CWEN on the remote system HS01.

  • Specify the system ID and transaction ID in the resource's local definition. The following table shows the fields that need updating
    Table Required Entry
    PCT Each remote transaction that can be initiated (using ATI) by a local transaction, specifying:
    Remote SYSID on the PCT Details page of ESMAC
    The ID of the SysC table entry for the remote system
    Remote PCT on the PCT Details page of ESMAC
    The name by which the transaction is known on the remote system. If you do not specify this field, the transaction is assumed to have the same name on both systems

No specific configuration is required for inbound transaction routing.

Parent topic: Transaction Routing
Related information
Common Configuration Tasks


Distributed Program Linking

Distributed program linking (DPL) enables a program running on MSS to link to a program running on a remote system. This provides an easy way to access DL/I (IMS) and SQL databases and BDAM files on a remote CICS system.

  • Restrictions on Distributed Program Linking
  • Abends When Using Distributed Program Linking
  • Configuration for Distributed Program Linking
Parent topic: Intersystem Communication


Restrictions on Distributed Program Linking

There are certain restrictions on the types of program to which you can link using the distributed program linking feature of MSS.

You cannot link to programs that:

  • Issue terminal control commands from a connected system back to MSS.
  • Inquire on terminal attributes.
  • Issue BMS commands.
  • Issue data interchange commands.
  • Address the TWA or the TCTUA. You must use the COMMAREA to pass data between systems, or you might get unpredictable results.
  • Issue syncpoints. DPL incorporates only sync level 1 logic. Whether you have single or multiple connected systems, a sync request can be propagated through all the connected systems. You should therefore take syncpoints from your system and not the invoked end of the link, otherwise you might get unpredictable results.

In addition to these restrictions, you should also be aware that when you are accessing DB2 from a transaction running on MSS, security access to the DB2 application plan is based on the transaction ID under which the program runs. The default transaction ID is one of the mirror transactions CPMI, CSMI and CVMI. To enable greater selectivity for DB2 application plans, you can specify an alternative transaction ID in either the PCT entry or in the EXEC CICS LINK command. This transaction muct be defined in the target system and must point to the mirror program DFHZCSMI. In all other respects (such as security attributes and task priority), the mirror transaction operates normally.

Parent topic: Distributed Program Linking


Abends When Using Distributed Program Linking

If the remote program terminates abnormally, the remote system's mirror program returns the last abend code to MSS, using the ASSIGN ABCODE command. The remote program might have handled other abends before terminating.

Parent topic: Distributed Program Linking


Configuration for Distributed Program Linking

This section describes any configuration required that is specific to distributed program linking. See the section Common Configuration Tasks for configuration that is required for all types of intersystem communication.

You might need to do some specific configuration for outbound distributed program linking. There are two ways of linking to a program on a remote system:

  • Specify the system ID of the remote system in the relevant EXEC CICS command. For example:
    EXEC CICS LINK TRANSID(PPQQ) SYSID(HS01)

    links to the transaction program PPQQ which belongs to the remote system HS01.

  • Specify the system ID and name of the resource in the resource's local definition. The following table shows the fields that need updating
    Table Required Entry
    PPT Each remote program to which a local program can link, specifying:
    Remote SYSID on the PPT Details page of ESMAC
    The ID of the SysC table entry for the remote system
    Remote Prog on the PPT Details page of ESMAC
    The name by which the program is known on the remote system. If you do not specify this field, the program is assumed to have the same name on both systems.
    Rmt Trans ID on the PPT Details page of ESMAC
    The name of the transaction (overriding the default mirror transaction ID) under which to run the remote program. This mechanism allows greater flexibility when the remote program accesses DB2 as the DB2 application plan is based upon the active transaction.
Note:

If local programs that use a different character set (ANSI or EBCDIC) are linked, you may need to set up data conversion facilities on the remote system.

Parent topic: Distributed Program Linking
Related information
Common Configuration Tasks


Distributed Transaction Processing

Distributed Transaction Processing (DTP) allows a CICS transaction running in one system to communicate with a transaction running in another system. The transactions are written and designed to communicate with each other over the intersystem communication link. DTP provides facilities so that two programs can communicate with each other, signal each other with regard to their status, and jointly commit modifications to protected resources.

DTP takes place between programs that are designed to be a matched pair. Their activities, command utilization, error protocols, and message formats must all be coordinated. MSS enables running transactions to initiate and communicate synchronously with transactions in remote systems that support the APPC protocols.

  • Restrictions on DTP
  • Configuring for DTP
Parent topic: Intersystem Communication


Restrictions on DTP

The following restrictions apply to Distributed Transaction Processing:

  • Process Initialization Parameter (PIP) data represented by the PIPLIST and PIPLENGTH operands for the CONNECT PROCESS and EXTRACT PROCESS commands is not transmitted by MSS, even though the operands are recognized by the MSS preprocessor.
  • Inbound transaction processing names can be no greater than four characters in length.
Parent topic: Distributed Transaction Processing


Configuring for DTP

The links to any interconnected system must be defined according to the examples provided in the section Network Links. You can either define any programs and transactions that are to participate in a DTP conversation through resource definition table entries on both the local and remote system or specify them in the CONNECT PROCESS and EXTRACT PROCESS commands.

Parent topic: Distributed Transaction Processing
Related information
Network Links


Network Links

The distributed processing facilities described above require that a network link is set up between the client and server systems. This section describes how to set up these links.

  • Types of Network
  • Supported Link Types
  • Communications Definitions
Parent topic: Intersystem Communication


Types of Network

This section describes the setting up of network links for the following types of communications network:

  • MSS to mainframe CICS and mainframe CICS to MSS
  • MSS to MSS

These are the network links that you can use for function shipping, asynchronous processing, transaction routing, distributed program linking and distributed transaction processing.

Parent topic: Network Links


Supported Link Types

You use TCP/IP network links for all types of Intersystem Communication .When you use TCP/IP to connect to the mainframe, you also need Micro Focus Mainframe Access Version 3.0 or above. Configuring MSS to use TCP/IP network links is described below.

Parent topic: Network Links


Communications Definitions

This section describes the definitions you need to make to enable communications. To create the necessary definitions you use the SysC page in ESMAC: from the Server page, click the Services dropdown in the Resources group in the left-hand menu, click By type, then click SysC. You see the list of existing SysC definitions. Click SysC in the New panel of buttons at the bottom of the page.

You must set the following fields:

Name | The name of the target system: this is also the value you enter in SYSID when you define a remote transaction
MF Node | The text host name or dotted decimal address of the target server
MF Port | The decimal value of the port that the target server listens on
Net Name | The name of the target enterprise server or CICS region
Session Max | The maximum number of send sessions

You need a connection definition for the enterprise server that is initiating the conversation. If you create a connection definition in both enterprise servers and both servers try to initiate the connection, MSS resolves the contention.

If you specify the home enterprise server as the target enterprise server (that is, Net name is the same as the name of the current enterprise server), MSS ignores the entry. This is useful because it enables a number of servers to share a single group that specifies the connections for all the regions.

You also need to add a listener for Intersystem Communication to each enterprise server that uses ISC. For more information see the section Common Configuration Tasks.

  • MSS-to-mainframe Example
  • Bidirectional MSS-to-mainframe Example
  • MSS-to-MSS Example
Parent topic: Network Links
Related information
Common Configuration Tasks


MSS-to-mainframe Example

In this example an MSS-enabled enterprise server is to be connected to a CICS region on a mainframe using TCP/IP and Mainframe Manager. The connection definition is shown below.

Figure 1. Example of MSS to Mainframe Connection Definition
Example of MTO to Mainframe Connection Definition

The name of the definition, RSYS in this example, must match the server name as defined in the Mainframe Access server definition, which in turn points to the target CICS region on the mainframe. This example would have a Mainframe Access server definition similar to the folllowing:

<MCOID=RSYS>
LUNAME=CICSTSR3
TPNAME=*
MODENAME=#INTER
SYNCLEVEL=0
SECURITY=NONE
<END>
Parent topic: Communications Definitions


Bidirectional MSS-to-mainframe Example

You must configure the Mainframe Access Server to enable ES/MSS outbound communications and provide it with definitions for the target CICS and target ES/MSS systems.

You must also create an appropriate connection definition for your enterprise server. The connection definition is shown below.

Figure 1. Example of MSSto Mainframe Connection Definition
Example of MTO to Mainframe Connection Definition

As with the previous example, the name of the definition, RSYS in this example, must match the server name as defined in the Mainframe Access server definition, which in turn points to the target CICS region on the mainframe. This example would have a Mainframe Access server definition similar to the folllowing:

<MCOID=RSYS>
LUNAME=CICSTSR3
TPNAME=*
MODENAME=#INTER
SYNCLEVEL=0
SECURITY=NONE
<END>
Note: If your enterprise server is not going to initiate the communications, you can omit the connection definition.
Parent topic: Communications Definitions


MSS-to-MSS Example

Two MSS-enabled enterprise servers, PEERSRV1 and PEERSRV2, are to be connected using CCITCP. Two connection definitions are shown, although only one is required.

The connection definition for the first region is shown below.

Figure 1. Example Connection Definition for PEERSRV1
Example Connection Definition for PEERSRV1

The connection definition for the second region is shown below.

Figure 2. Example Connection Definition for PEERSRV2
Example Connection Definition for PEERSRV2
Parent topic: Communications Definitions


Setting Up Communications with Mainframe CICS Regions

This section describes how to configure communication links between CICS regions operating on an Enterprise Server environment, and mainframe CICS regions.

Note:

This functionality is available for both Windows and UNIX environments.

You can also configure links between an Enterprise Server environment, and files residing on a mainframe. This functionality is covered in a different area of the help.

  • Connecting to a Mainframe: Overview
  • System Architecture
  • Communications software requirements
  • Process Overview
  • Configuration Definitions
  • Mainframe Connection Information Requirements for 802.2 DLC
  • Installing the Communications Server Software
  • Configuring Communications Server to Mainframe Communication
  • Connecting a Client to the Host CICS Region
  • Defining a CICS Connection from the Host to the Local COBOL System
  • Setting Up Communications from Host to Local CICS System
Parent topic: CICS Support
Related concepts
Working with Mainframe Files


Connecting to a Mainframe: Overview

The configuration described in this section uses an SNA link between CICS applications running on a mainframe and CICS operating on a local COBOL system, that is one that operates on one or more local Windows or UNIX machines.

Note:

This functionality allows Enterprise Server to connect to a remote peer system using a SYS62 connection and support the standard 2-Phase Commit protocol.

One of the benefits that this functionality provides is that it improves transactional data integrity between CICS applications running on a UNIX platform, and CICS applications running on a mainframe under z/OS.

CICS Communications with mainframe CICS regions using SYS62 connections have been tested with z/OS version 1.13.

To configure a link between Enterprise Server and Mainframe CICS regions, you should be familiar with:
  • The concepts of a CICS system, and how it can operate over multiple machines in a single system environment
  • CICS intersystem communication requirements.
  • Configuring the communications software on the local server.
  • Configuring the communications software on the client.

For information on communication between IBM CICS products, see the IBM publication CICS Family: Interproduct Communication, SC33-0824.

Parent topic: Setting Up Communications with Mainframe CICS Regions


System Architecture

A system that connects a mainframe CICS region and an Enterprise Server CICS region uses communications server software, for example to manage SNA communications.

  • In the Windows environment, Microsoft Host Integration Server.
  • In a Sun Solaris UNIX environment, SNAP-IX

An installation typically consists of:

  • A mainframe running CICS applications.
  • A PC or a UNIX communications server with a dedicated SNA link to the mainframe. This runs communications server software, and acts as an SNA manager.
  • One or more client PCs or UNIX machines running communications server SNA client software, and Enterprise Server COBOL systems.

For details of the communication server's hardware and software requirements, refer to the documentation for the communications software that you are using.

Parent topic: Setting Up Communications with Mainframe CICS Regions


Communications software requirements

The communications software that you use depends on your platform. Available platforms and the corresponding communications server software to use with each is as follows:

  • AIX

    IBM Communications Server for AIX 6.4.0.2

  • HP-UX

    HP-UX SNAplus2 Link R7.11

  • Microsoft Windows

    Microsoft BizTalk Host Integration Server 2009

    Note:
    • If you are installing this on a 64-bit machine, the installation process installs only the 64-bit libraries.
    • You need a 64-bit enterprise server in order to use a SYS62 connection with Microsoft BizTalk Host Integration Server.
  • Red Hat/SUSE Linux

    IBM Communications Server for Linux 6.4.0.2

  • Red Hat/SUSE Linux on zSeries

    IBM Communications Server for Linux on zSeries 6.4.0.2

  • Solaris

    Metaswitch SNAP-IX 7.02.008

  • z/OS

    CICS Communications with mainframe CICS regions using SYS62 connections have been tested with z/OS version 1.13.

Parent topic: Setting Up Communications with Mainframe CICS Regions


Process Overview

To set up an SNA link between a mainframe CICS environment and CICS regions on local enterprise servers, follow the procedures outlined in the following four stages. The procedures describe how to configure an 802.2 DLC connection:

  • Configure the communication link between the local SNA Communications server and the mainframe host:

    This stage involves installing the SNA Server software on the local SNA Communications server and any clients running Enterprise Server, and configuring the SNA link from the local SNA Communications server to the mainframe.

  • Connect the local CICS system to the Host CICS region:

    This stage involves configuring the connections between the local CICS systems (running on any clients), and the CICS region running on the host.

  • Define the client connections and sessions to the host:

    This stage involves defining the local connections and sessions to the host CICS region, so that the host can recognize sessions running on the client COBOL system.

  • Set up communications from the host to the local CICS system:

    This stage involves configuring the link so that the host can initiate tasks on a local CICS system.

This chapter provides an overview of the procedures in each stage. For detailed information on each procedure, refer to the documentation delivered with the SNA Communications software that you are using.

Each procedure includes a list of the information you need to configure an 802.2 DLC connection. You can collect this information from your mainframe system administrator. An example value is included for each setting required. These example values are used consistently across the procedures described in this chapter, to help clarify situations where different procedures use the same values.

Parent topic: Setting Up Communications with Mainframe CICS Regions


Configuration Definitions

The terminology used often varies between environments and communications service managers used. The following table details the terminology that is used in this chapter. Alternative names are shown in parentheses.

Generic Term | Description
Client | A machine, running a COBOL system, where you install communications client software. This machine accesses a host CICS environment via a local server.
Data Link Control (DLC) link The interface to the network. The attributes of a link can be divided into two parts:
  • Characteristics of the port (logical and physical)
  • Control characteristics of the link
Control Point (CP, CP Name) | Identifies the local node manager that provides services to the local logical units.
Link station | The part of data link control (DLC) that is responsible for the transfer of data between two communications services managers connected by a link.
Local server | The machine with the SNA link to the host, where you install communications server software, to provide access to a COBOL System running on client PCs.
Network name (NETID) | The name of the network to which the system is connected.
Logical Unit (LU) | A network accessible unit (NAU). In SNA there are a number of logical unit types that identify the protocols supported by that logical unit. For APPC the LU type is 6.2 referred to as LU 6.2.
Partner LU | The logical unit with which to communicate.
Transaction Program (TP) | The program to be executed at one end of a conversation.
Session | The logical connection between two network accessible units.
Inter Systems Communications (ISC) | Two or more regions running on different processor complexes that are able to communicate with each other.
Mode | The connection characteristics of a session.
Parent topic: Setting Up Communications with Mainframe CICS Regions


Mainframe Connection Information Requirements for 802.2 DLC

For an 802.2 DLC connection, you require, from your mainframe system administrator, the information detailed in the table below. For each item, the table lists the configuration task that requires the information, and an example value. For details of the local information required, refer to each task.

Parameter from the VTAM System Administrator | Task and Example Value | Description
Remote Network Name (NETID) | Configuring the Local Server: HSTNET1 | The network name of the VTAM domain. All resources that comprise this VTAM domain are in this VTAM domain.
Local Control Point (CP) name assigned to the local server | Configuring the Local Server: MCOPU020 | The unique PU identifier created by the mainframe administrator for the local server. This is specified in the VTAM PU definition for this machine. That is, the CP name matches the PU identifier.
Remote Network Address | Configuring the Connection Address: 400000004044 | 12-digit hexadecimal network address of the remote host system's network controller.
Remote Control Point (CP) Name (also known as SSCPNAME) | Configuring the System Identification: HSTMVS | The name of the remote system
The XID format used by the host system | Configuring the System Identification: 3 (default) | The XID format can be either 0 or 3. A format of 3 is generally used for APPC (and must be used for independent APPC LUs). The older format, 0, tends to be used for 3270 devices.
Remote Node ID | Configuring the System Identification: None | An 8-digit hexadecimal number used to identify the host system on the SNA network. Your mainframe system administrator will advise whether or not you need to use this.
Local Node ID | Configuring the System Identification: 05D,22222 | An 8-digit hexadecimal number used to identify the local system on the SNA network. The first three digits are the IDBLK and the last five are the IDNUM. These must correspond with the IDBLK and IDNUM fields of the VTAM PU definition for this machine, as defined on the host system.
Maximum Basic Transmission Unit (BTU) Length (also known as I-Frame) | Configuring 802.2 DLC Properties: 1493 | The number of bytes that can be transmitted in a single data link control frame. This is calculated by subtracting 9 from the MAXDATA parameter of the PU definition for this machine (that is, maximum BTU length = MAXDATA - 9). This is a maximum value. The actual value used is negotiated to the highest value below this figure that is acceptable to both partners.
List of independent LUs for your PU definition. | Configuring Local APPC LUs: MCOLU021 | These LUs are required for APPC and are defined in the list of LUs defined for your PU on VTAM. You can have multiple independent LUs per PU. All independent LUs for your PU have LOCADDR set to zero under the PU definition on VTAM.
Target LU Name | Configuring Remote LUs: HSTCICS1 | This should match the LU definition as it exists on the remote system, in this case, a VTAM APPLID definition on the host system. To communicate with a host CICS system, this is the APPLID of the host CICS environment .
List of the dependent LUs defined as terminals with their associated LU number for your VTAM definition. Configuring a 3270 LU for the 3270 Applet:
  • MCOTRM22,2
  • MCOTRM23,3
  • MCOTRM24,4
These LUs are used for terminals to the host. They are not required for APPC, but are very useful for the host CICS configuration. They are found under your PU definition on VTAM. The LU number must match the associated LOCADDR number for this named LU.
The Mode Table defining the session limits for the connection | Configuring Remote LUs: #INTER | This is used to negotiate the session limits with the host. Normally the host would use the default mode of #INTER. If #INTER is not appropriate, you can define and use another mode. If you need to define another mode, your VTAM system administrator should be able to supply the parameters required, and the Host Integration Server 2006 Helpthe Host.
Parent topic: Setting Up Communications with Mainframe CICS Regions


Installing the Communications Server Software

You need to install the communications server software on both the communications server, and on Enterprise Server clients that connect to it. The process varies depending on your environment and the communications server software that you use.

  • Installing the Communications Server Software on the Local Server
  • Installing the Communications Software on the Local Clients
Parent topic: Setting Up Communications with Mainframe CICS Regions


Installing the Communications Server Software on the Local Server

In this procedure, you install the communications server software onto the local communications server, and add the configuration details required to define the local server.

Parameter | Example value | Origin and description
Remote network name (NETID) | HSTNET1 | Mainframe administrator: the VTAM domain's network name.
Local control point (CP) name assigned to the local machine | MCOPU020 | Mainframe administrator: the VTAM PU assigned to the local Microsoft HIS server.
Parent topic: Installing the Communications Server Software


Installing the Communications Software on the Local Clients

In this procedure, you install the communications software onto each of the local Enterprise Server clients.

Parameter | Example value | Origin and description
Sponsor server | NY-HOST-5 | The network name of the host system.
SNA Service Account | NYDOMAIN\MCOU | A valid user ID for the system
Parent topic: Installing the Communications Server Software


Configuring Communications Server to Mainframe Communication

For specific details on performing each stage outlined in this section, refer to your communications server software documentation.

To enable a mainframe CICS environment to communicate with an Enterprise Server COBOL system attached to the communications server, an LU 6.2 link is required between the local server and the mainframe. The LU 6.2 link is separated into SNA Server (PC) and VTAM (mainframe) components.

  • Configuring the Link Service for the local server
  • Configuring the connection
  • Configuring the remote system's network address
  • Configuring the System Identification
  • Configuring 802.2 DLC Properties
  • Configuring Local APPC LUs
  • Configuring Remote LUs
  • Adding a User
  • Configuring a 3270 LU for Terminal Access
  • Associating a 3270 LU with a User
  • Activating the Configuration in the Windows Environment
Parent topic: Setting Up Communications with Mainframe CICS Regions


Configuring the Link Service for the local server

In this procedure, you create a new DLC 802.2 Link Service and specify the network adaptor that the link service uses.

Parameter | Example value | Origin and description
Link service name | SNADLC1 | User-assigned
Adapter | 4 | User-assigned

If the local server has more than one PU to the mainframe, you will need more than one link service. Each PU to a host requires a unique Local Service Access Point (SAP) address. If you are defining your first link service, use the default of 4. For a host with multiple PUs, the link service adapter number must be a hexadecimal number that is a multiple of 4, and is in the range of 04 to EC.

Parent topic: Configuring Communications Server to Mainframe Communication


Configuring the connection

In this procedure, you define the 802.2 connection for the local server.

Parameter | Example value | Origin and description
Connection name | MVSHOST1 | User-assigned
Link service | SNADLC1 | Defined when you configure the local server
Remote End | Host System | Defines the mainframe as the remote system
Allowed Directions | Both Directions | Allows communications in both directions
Activation | By Administrator | Can change this after testing to either On Demand, or At Server Startup
Parent topic: Configuring Communications Server to Mainframe Communication


Configuring the remote system's network address

In this procedure, you configure the remote system's network address.

Parameter | Example value | Origin and description
Remote Network Address | 400000004044 | Mainframe system administrator: Network address of the remote host system's network controller
Parent topic: Configuring Communications Server to Mainframe Communication


Configuring the System Identification

In this procedure, you configure the remote network system identification details.

Parameter | Example value | Origin and description
Remote Network Name | HSTNET1 | Mainframe system administrator: The network name of the VTAM domain.
Local Control Point Name | MCOPU020 | Mainframe system administrator: the VTAM PU identifier assigned to the local machine.
Local Node ID | 05D,22222 | Mainframe system administrator: identifies the local system on the SNA network.
XID Type | Format 3 | Mainframe system administrator: can be either 0 or 3, generally 3.
Remote Network Name | HSTNET1 | Mainframe system administrator: The network name of the VTAM domain.
Remote Control Point Name | HSTMVS | Mainframe system administrator: The name of the remote system
Remote Node ID |  | Mainframe system administrator will advise whether you need to use this. Identifies the host system on the SNA network.
Parent topic: Configuring Communications Server to Mainframe Communication


Configuring 802.2 DLC Properties

In this procedure, you configure the maximum Basic Transmission Unit (BTU) length for the connection.

Parameter | Example value | Origin and description
Max BTU Length | 1493 | The maximum number of bytes that can be transmitted in a single data link control frame. The actual value is the maximum value acceptable to both partners, up to the maximum value.

Before attempting to communicate to the host you must define the local and remote LUs that will be used to communicate over the SNA connection you have configured.

Parent topic: Configuring Communications Server to Mainframe Communication


Configuring Local APPC LUs

In this procedure, you configure the Local APPC Logical Units (LUs). Independent LUs are used to communicate over the host connection. You need to configure:

  • Local Advanced Program to program Communication (APPC) LUs
  • Remote LUs
Parameter | Example value | Origin and description
LU Alias | MCOLU021 | Mainframe system administrator: defined in the list of LUs configured for your PU on VTAM.
LU 6.2 type | Independent |
Network Name | HSTNET1 | Mainframe system administrator: The network name of the VTAM domain.

If you are using multiple APPC LUs, you can configure each of them as follows:

Parent topic: Configuring Communications Server to Mainframe Communication


Configuring Remote LUs

In this procedure, you configure a remote Logical Unit ( LU) that is assigned to a connection.

Independent LUs are used to communicate over the host connection. You need to configure:

  • Local Advanced Program to program Communication (APPC) LUs
  • Remote LUs: When communicating with host systems running VTAM (or NCP), the Remote LU is known as the APPLID.
Parameter | Example value | Origin and description
Connection | MVSHOST1 | Defined in the Configuring the Connection task.
LU Alias | HSTCICS1 | Mainframe system administrator: This LU name should match the definition of the LU as it exists on the remote system, in this case in the form of a VTAM APPLID definition on the host system. To communicate with a host CICS system, this is the host CICS APPLID.
Implicit Incoming Mode | #INTER | Mainframe system administrator: Used to negotiate the session limits with the host.
Network Name | HSTCICS1 | Defaults to the value specified for the connection
Note:

When a connection is established between a Local LU and a Remote LU, the Mode characteristics are negotiated. The partner system (for example, the mainframe) may reduce the session limits, and fewer client sessions than expected may be supported. Hence it is important that the Mode characteristics as defined for both the Local and Remote LUs are compatible.

Parent topic: Configuring Communications Server to Mainframe Communication


Adding a User

Before you can use a connection you need to be defined to the communications server as a user.

Parameter | Example value | Origin and description
User | MCOU | User-defined. A user name.
Parent topic: Configuring Communications Server to Mainframe Communication


Configuring a 3270 LU for Terminal Access

In order to enable terminal access to the host system, a 3270 LU must be configured for use by each terminal session.

This operation can be repeated for other 3270 dependent LUs for your PU. With a 3270 LU configured with the values below, the operation could be repeated for LU MCOTRM23 with an LU number of 3, and MCOTRM24 with an LU number of 4.

Parameter | Example value | Origin and description
LU number | 2 | Mainframe system administrator: LUs used for terminals to the host.
LU name | MCOTRM22 | Mainframe system administrator: LUs used for terminals to the host.
Parent topic: Configuring Communications Server to Mainframe Communication


Associating a 3270 LU with a User

When a user runs a terminal emulator session, a 3270 LU is required in order to establish a 3270 session with the host system. This LU may come from a pool of 3270 LUs or it may be associated with the user. The example values define a pool and associate a user to this pool.

Parameter | Example value | Origin and description
Pool | DevPool | User-defined
Display Model Attributes | 2 (25x80) |
Assign to user | MCOU | A user that you have configured
Parent topic: Configuring Communications Server to Mainframe Communication


Activating the Configuration in the Windows Environment

To activate the configuration in the Windows environment, you must stop and restart the Server service.

Provided the 'Activation Type' was defined as 'On Server Startup' or 'On Demand', when the server is active, the underlying connections activate.

When configured for Incoming and Outgoing calls, the status for Connections becomes 'On Demand/Incoming' when successfully activated. The connection status becomes 'Active' when the first session is established, or if the connection is activated manually by the administrator.

Parent topic: Configuring Communications Server to Mainframe Communication


Connecting a Client to the Host CICS Region

Once you have configured communications server software on the server, you can configure each client to communicate with the host CICS region.

  • Client - Host Configuration Parameters
  • To Define a Client Connection to a Host CICS System
  • To Include the Resource Group in the Startup List
Parent topic: Setting Up Communications with Mainframe CICS Regions


Client - Host Configuration Parameters

The parameters that you require for configuring the client to the host are:

Client Name | From your VTAM Administrator | Host CICS Name as in CEDA | Example Value | Matching SNA Server Parameter
LU alias | Independent LU for the connection's PU that you are going to use |  | MCOLU021 | SNA Server value for 'LU Alias' in the 'Local APPC LU' definition for the APPC LU that you are going to use
Partner alias | Target LU name for your connection |  | HSTCICS1 | SNA Server value for 'LU Alias' in the 'Remote APPC LU'; the host CICS system's APPLID
Alias applid | The APPLID of the local client as defined to the host. This is not in the list above because it takes a default value. |  | MCOLU021 | SNA Server value for 'LU Name' in the 'Local APPC LU' definition for the APPC LU that you are going to use. Normally the same as 'LU Alias'.
Mode table | The mode table defining the session limits for the connection | 'MOdename' under 'Session Identifiers' | #INTER | SNA Server value for 'Implicit Incoming Mode' in the 'Remote APPC LU'
Net name | Your local CICS system's network name. This is the same as Alias APPLID. | 'Netname' under 'Connection Identifiers' | MCOLU021 | SNA Server value for 'LU Name' in the 'Local APPC LU' definition for the APPC LU that you are going to use. Normally the same as 'LU Alias'.
Parent topic: Connecting a Client to the Host CICS Region


To Define a Client Connection to a Host CICS System

To define a client connection to a host CICS system use the Enterprise Server Administration interface.

  1. Open the Enterprise Server Administration screen, and on the administration page click Start next to the name of the CICS server you want to use.
  2. ClickDetails next to the name of the server and navigate to Server...> Control> ES Monitor and Control. The Server information page is displayed.
  3. In the Resources panel on the sidebar, choose by Group from the list and then click Groups.
  4. Add a new group or choose a group to add your connection definition to. Click Details next to the group's name.
  5. On the details page click Sys62. This opens the page for creating a LU6.2 system connection.
  6. Enter the following values:
    • Name of the Sys62.

      This name does not relate to any other setting on the mainframe. The name value you choose for this is the one you use in your programs or in a terminal.

      For example CRTE SYSID=XXXX where XXXX is the name of the Sys62 connection that you have defined here.

    • (Optional) Description of the Sys62.
    • In the LU Alias field, enter the independent LU name for your PU as defined on VTAM.
    • In the Partner Alias field, enter the APPLID of the remote CICS system.
    • In the Net Name, enter the APPLID of the remote system or region.
    • In the APPLID field, enter the APPLID of the local system as defined to the host.
    • In the Mode table field, enter the mode table that the SNA Server and the host are to use.
    • In the Session maximum field, enter the maximum number of sessions between LU-LU pairs. The maximum number supported is: 5.
  7. Click Group list to return to the group’s details page.
  8. Click PPT. The Processing Program Table page opens.
  9. Enter the following values:
    • PPT name.
    • (Optional) Description.
    • Remote SysID. The value should be equal to the name you have entered for the Sys62.
  10. Return to the Server home page.
Parent topic: Connecting a Client to the Host CICS Region


To Include the Resource Group in the Startup List

To include a resource group in the startup list use the Enterprise Server Administration interface.

  1. Open the Enterprise Server Administration page and click Start next to the name of the CICS server you want to use.
  2. Click Details next to the name of the server and navigate to Server... > Control > ES Monitor and Control. The Server information page is displayed.
  3. In the Resources panel on the sidebar, choose by Group from the list and then click Groups. A list of all resource groups that are currently included in the host CICS system's definitions is displayed.
  4. Click New. The new group page is displayed.
  5. Enter:
    • Name of the group.
    • (Optional) Description of the group.
Parent topic: Connecting a Client to the Host CICS Region


Defining a CICS Connection from the Host to the Local COBOL System

In order for the host CICS region to recognize a COBOL system running on a local client, you need to define a connection definition and an associated session on the host. On most host systems, a CICS region change such as this is usually applied by the system administrator. Liaise with your system administrator to perform this process.

You need to have a resource group for the connection and session definitions. The example group value is HSTTOSNA. The example connection name is LU21 and the session name is LU21SESS.

You can use an SNA Server 3270 applet to configure the host CICS system by entering the VTAM ID of your host CICS region when the terminal has a connection to the host VTAM system.

  • Using the CEDA Transaction to Configure the Host CICS Regions
  • Defining a Terminal for Transaction Routing
  • Installing the Definitions
  • Configuring a Default Terminal
  • Testing the Connection to the Host CICS System
  • Starting the Local CICS Connection
Parent topic: Setting Up Communications with Mainframe CICS Regions


Using the CEDA Transaction to Configure the Host CICS Regions

This procedure describes how to use the IBM-supplied transaction CEDA to configure the host CICS regions. For more information on the CEDA transaction, see the IBM publication CICS/ESA 3.3 Resource Definition.

In the following procedures, accept the default values for the fields that are not described. When you have defined your connection and sessions, and have tested them, you can configure the connections and settings to be installed automatically on the host CICS region at startup. You can do this by adding the group to your CICS startup list.

  1. In CICS, on the host system, enter the following transaction:

    transaction 'CEDA DEFINE GROUP(group_name) CONNECTION(connection_name)

    where group_name is the name of the group containing the connection connection_name. A transaction using the example values in this chapter is:

    CEDA DEFINE GROUP(HSTTOSNA) CONNECTION(LU21)

  2. In the Netname field, under Connection Identifiers, type the netname of you local COBOL system and press Enter. You should receive the message Define Successful near the bottom of the screen.
  3. Press PF3 to end CEDA, followed by Clear.
  4. Enter the transaction:

    CEDA DEFINE GROUP(group_name) SESSION(session_name)

    where group_name is the name of the group containing the session session_name. A transaction using the example values in this chapter is:

    CEDA DEFINE GROUP(HSTTOSNA) SESSION(LU21SESS)

  5. In the Connection field, under Session Identifiers, type the name of the connection you have defined. The example value is LU21.
  6. In the MOdename field, under Session Identifiers, type the name of the mode table that you are using. The example value is #INTER.
  7. In Session Properties you need to enter the maximum number of sessions in the group and the maximum number of contention winners. Example values are 8 and 4 respectively.
  8. If required, change send size and receive size default values. This will depend on your mode table.
  9. Press Enter and you should receive the message Define Successful near the bottom of the screen.
  10. Press PF3 to end CEDA, followed by Clear.
Parent topic: Defining a CICS Connection from the Host to the Local COBOL System


Defining a Terminal for Transaction Routing

On some versions of VTAM you might need to define a terminal so that you can perform transaction routing to the host CICS region from the local COBOL system.

This requirement is indicated by the error message TXCS1012E Comms error x'0006' during route of TRAN to system HST1 when you enter the first transaction ID to be run on the host CICS region.

If you define a transaction routing terminal, you also need to change the default terminal configuration. The example transaction routing terminal is: L21A.

  1. Enter the transaction:

    CEDA DEFINE GROUP(group_name) TERMINAL(terminal_id)

    where group_name is the name of the group containing the terminal_id terminal definition. With the example values, the command is

    CEDA DEFINE GROUP(HSTTOSNA) TERMINAL(L21A)

  2. Enter the following details under Terminal Identifiers:
    • Typeterm = DFHLU2
    • Netname=L21A
    • REMOTESYSTem = LU21
    • REMOTEName = L21A
  3. Press Enter and you should receive the message 'Define Successful' near the bottom of the screen.
  4. Press PF3 to end CEDA, followed by Clear.
Parent topic: Defining a CICS Connection from the Host to the Local COBOL System
Related information
Configuring a Default Terminal


Installing the Definitions

After you have defined the connection, the session, and, if required, the terminal, you need to install the terminal definitions. As a connection and a session are paired, you need to install the group that they are contained in rather than the individual entries.

  • Using the example values, on your host CICS region, enter:

    CEDA INSTALL GROUP(HSTTOSNA)

    The message: Install Successful is displayed.

Parent topic: Defining a CICS Connection from the Host to the Local COBOL System


Configuring a Default Terminal

You only need to do this if you receive the following message when you enter the first transaction ID to be run on the host CICS region:

TXCS1012E Comms error x'0006' during route of TRAN to system HST1

To configure a default terminal use the Enterprise Server Administration interface.

Parent topic: Defining a CICS Connection from the Host to the Local COBOL System
Related information
Defining a Terminal for Transaction Routing


Testing the Connection to the Host CICS System

To test your connection to the host CICS system you need to ensure that:

  1. The local communications server has an active link to the host.
  2. The host CICS region is running. In most installations this is the case, but sometimes you may need to ask your host system administrator to start the host CICS region that you are going to connect with. It can usually be tested by using an SNA Server 3270 applet and entering the VTAM ID of your host CICS region when the terminal has a connection to the host VTAM.
Parent topic: Defining a CICS Connection from the Host to the Local COBOL System


Starting the Local CICS Connection

To start the local CICS connection use the Enterprise Server Administration interface.

  1. Open the Enterprise Server Administration page, and click Start next to the name of the CICS server you want to use.
  2. With a 3270 terminal emulator connect to the CICS region.
  3. Complete any sign-on procedure required by your system.
  4. Enter the transaction:

    CRTE SYSID=HST1

    where HST1 is your connection definition name. You should receive the following message:

    DFH4409 The routing session to system HST1 has been started

    This initiates transaction routing for this terminal without acquiring any resources. It does not test the connection.
  5. To test the connection, enter a transaction that you know exists on the host CICS system. A suitable transaction is:

    CEMT INQUIRE CONNECTION

    This should return the following information:
    IN CONN
STATUS:  RESULTS - OVERTYPE TO MODIFY
Con(COA1) Net(COA1REMT)  Ins Rel  Vta Appc
Con(LU21) Net(MCOLU021)  Ins Acq  Vta Appc

    In the list of connections, you should see the connection that you have defined, and the netname associated with it. It should also have the acquired status (Acq).

Parent topic: Defining a CICS Connection from the Host to the Local COBOL System


Setting Up Communications from Host to Local CICS System

At this stage, you are not able to use transaction routing, function shipping, or DPL from the host CICS region. Also, distributed transaction processing (DTP) does not work because the host CICS region is currently unable to initiate tasks on the local CICS system.

If you have reached this point successfully, you should now have the communications server software on the local server configured and connected to the VTAM host system. The local CICS system should be able to use transaction routing, function shipping, and distributed program linking (DPL) to the host system.

  • Defining Transaction Programs
  • Testing Inbound Transaction Routing from the Host
Parent topic: Setting Up Communications with Mainframe CICS Regions


Defining Transaction Programs

In this procedure, you define transaction programs (TPs) to the local communications server (or client connected to the communications server) so that it knows how to invoke a CICS program invoked from the mainframe.

The following TPs must be defined for inbound function shipping, transaction routing, and distributed program linking:

TP Name | CICS Transaction | Purpose
CPMI | CPMI | Function shipping mirror transaction for ANSI
CSMI | CSMI | Function shipping mirror transaction, general
CVMI | CVMI | Function shipping mirror transaction for EBCDIC
CRTE | CRTE | Transaction routing transaction
CRSR | CRSR | Internal CICS housekeeping transaction

For inbound function shipping, transaction routing, or distributed program linking, you must add the resource group DFHISC to the startup list in the SIT that contains the PCT definitions for the above transactions.

To define a transaction program:

  1. Add a New TP and specify the transaction name. This is used to identify the transaction program to the SNA Server. This TP name should correspond to the transaction that the host system attempts to run on the local CICS region (for example, CRTE).
  2. Setup/configure the transaction that will run on the local CICS region, specifying the region (REGIONNAME), transaction (TTPNAME) and parameters, where:
    • REGIONNAME is the name of your region, for example: MSSDEMO
    • TPNAME is the name of your transaction program, for example CRTE
    • the name of the Local LU Alias as defined to the SNA server for the inbound request. This is the independent LU that you are going to use for your PU as defined to VTAM. The example value is: MCOLU021

Include the 'TP Name' table in the generic section.

  • Defining Transaction Programs using a HIS connection
Parent topic: Setting Up Communications from Host to Local CICS System


Defining Transaction Programs using a HIS connection

Note: The information in this section relates specifically to Windows systems using Microsoft BizTalk Host Integration Server (HIS). For other Advanced Program-to-Program Communications (APPC) software, the command names used will vary, but the overall details added will be the same.

For inbound communications, the HIS SNA Server requires registry entries to be created for each CICS transaction on the local server or a client. These entries are used by the HIS SNA Server to start the CICS program dfhgatch.exe, which routes the request to the correct CICS region and transaction.

The Micro Focus CICS registry entries for the transaction programs can be found in the following location:

/HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services/SnaBase
   /Parameters/TP's/tpname/Parameters

To add a new or overwrite an existing registry entry for an inbound transaction program for HIS:

  1. Start an Enterprise Server command prompt.
  2. From the prompt, run tpsetup.exe. The TP Setup dialog box is displayed.

    tpsetup.exe is supplied with the HIS software.

  3. Click Add to display the Add New TP dialog box.
  4. In the TP Name field, enter the transaction name. This is used to identify the transaction program to the HIS SNA Server. This TP name should correspond to the transaction that the host system attempts to run on the local CICS region (for example, CRTE).
  5. In the Command line field, specify an entry to run casatch.exe. This starts the transaction on the local CICS region. The entry will depend on the bit-version of your Enterprise Server region.
    CAUTION:

    Be sure that you specify the path to the correct casatch.exe bit-version corresponding to the region (not the installed Enterprise Server software) that you are using.

    For example, the default locations for Enterprise Developer are:

    • For 32-bit systems: %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin\base\bin\casatch.exe
    • For 64-bit systems: %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin64\base\bin\WIN64\casatch.exet
  6. In the Parameters field, specify the region, transaction and parameter details.
    This will generally be in the format: /RREGIONNAME /TTPNAME where:
    • REGIONNAME is the name of your region, for example MSSDEMO
    • TPNAME is the name of your transaction program, for example CRTE
  7. Specify the name of the Local LU Alias as defined to the HIS SNA server for the inbound request. This is the independent LU that you are going to use for your PU as defined to VTAM. The example value is: MCOLU021
  8. Click OK

For information on adding and editing transaction programs, see the Host Integration Server 2006 Help.

Note:
  • tpstart.exe reads the registry only when it is started. So, if you have updated the registry by adding or changing a TP, you need to stop and restart tpstart.exe to pick up any updates.
  • casatch.exe fails unless it is run under the same userid, or a userid with identical privileges, as the local Enterprise Server region. Therefore, either the Enterprise Server region must be started from a normal Enterprise Developer command prompt (using the casstart command), or MFDS must be started from a normal Enterprise Developer command prompt, using the mfds command. That is, as opposed to running MFDS as a service.

    If MFDS is running as a user process, started from the command prompt, then you can use either casstart or the user interface.

Parent topic: Defining Transaction Programs


Testing Inbound Transaction Routing from the Host

When you have added the required TP definitions to the registry, you are able to perform inbound transaction routing from the host.

This test completes the configuration. To test your connection to the host ensure that:

  1. The communications server has an active link to the host.
  2. The host CICS region is running. In most installations this is normally the case, but sometimes you may need to ask your host system administrator to start the host CICS region that you are going to connect with. It can usually be tested by using a communications server 3270 applet and entering the VTAM ID of your host CICS region when the terminal has a connection to the host VTAM.
  3. You have restarted the region as described in the section Starting the Local CICS Connection.

When the previous steps have been done:

  1. Start a communications server applet to the host VTAM, as described earlier, and connect to the host CICS region.
  2. When you have a session on the host CICS region, run the supplied transaction:

    CRTE SYSID=localwhere local is the name of the connection that you defined earlier. With the supplied example values, it is:

    CRTE SYSID=LU21

    .
  3. You should now be able to use the SNA Server 3270 applet as if it was a terminal on your local CICS system. To test the connection, run the transaction CENV supplied with the Enterprise Server CICS software. This should give you information about your local CICS system. When you have completed transaction routing, enter the CANCEL command.
Note:

When transaction routing is active in one direction, you cannot then route back to your terminal. This is because when you attempt to route back, the original terminal-id is passed back and is rejected because it is not unique. All terminal-ids must be unique within a CICS region, both on the host and the local client.

Parent topic: Setting Up Communications from Host to Local CICS System
Related information
Starting the Local CICS Client


Configuring CICS Terminals and Printers

  • Overview
  • Using Telnet 3270 terminal emulators
  • Defining Terminal Models
  • Enabling CICS Printer Support
  • Configuring the Autoinstall Exit
  • Autoinstall Control Program Call Interface
  • Autoinstall Processing
Parent topic: CICS Support


Overview

The user interface to CICS applications running in Enterprise Server is through 3270 terminal emulators. These enable Enterprise Server to display CICS application input and output screens using 3270 data streams, and to receive input.

Note:

We recommend that you use a Telnet 3270 (TN3270) client such as Micro Focus RUMBA.

Parent topic: Configuring CICS Terminals and Printers


Using Telnet 3270 terminal emulators

You can use third-party TN3270 terminal emulators as CICS clients. The TN3270 emulator session can run on the same machine as Enterprise Server or on a network machine.

To use a TN3270 terminal emulator, you need to create a TN3270 listener in Enterprise Server Administration.

When you specify the Endpoint for the listener, we recommend that you use any port number above 5000 that isn't in use, since the usual port number for Telnet, 23, might already be in use for non-3270 Telnet access.

The TN3270 emulator session can run on the same machine as Enterprise Server or on a remote machine.

By default MSS installs TN3270 terminals dynamically as basic 3270 terminals. This means that some of the more advanced features of your TN3270 terminal emulator won't be available. To make these features available, you need to enable MSS to associate the TN3270 device type and a CICS typeterm definition, known as a T-Type in ESMAC.

The TN3270 device type is specified by the emulator software and might or might not be configurable. Device types indicate the ability of the emulator to support various elements of the 3270 data stream, for example, color, extended attributes, the use of a TCTUA etc.

During the connection negotiation the TN3270 client sends a data packet indicating which device it wishes to emulate. MSS uses this data to identify a T-Type entry which defines this terminal type.

To make this work you need to:

  1. Define a T-Type entry that matches the capabilities of the TN3270 terminal emulator.
  2. Define a terminal model entry on the ESMAC Term page which points to this typeterm definition. Required fields for the terminal model entry are:
    Name | Unique name of this terminal model
    Model | O(nly), Y(es) , or N(o)
    Model name | The TN3270 device type
    Terminal type | The name of the T-type entry to use with this terminal

For example, suppose the TN3270 client software is configured to emulate an IBM 3279 MOD2 with support for extended attributes. At connection time MSS searches for a terminal model entry with the name TN32792E. The terminal type specified in this terminal entry is then used to look up the terminal's details in the T-type entry .

Configuring screen size

If you want to use a screen size other than the default, which is MOD2 (24 x 80), you need to set the environment variable ES_TN3270_FORCE_ALT=Yes before starting the enterprise server. You can then change the size to MOD1 (12 x 80), MOD2 (24 x 80), MOD3 (32 x 80), MOD4 (43 x 80), and MOD5 (27 x 132) during the terminal session.
Note: Micro Focus terminal handling does not support dynamic window sizing. If you switch from a larger terminal to a smaller one, then the window size will remain at the larger window's dimensions.

To use custom dimensions, you need to set ES_TN3270_FORCE_ALT=Yes and also specify the screen size in the Alt. Screen Width and Alt. Screen Height fields of the ESMAC T-Type page.

  • To specify a listener for TN3270 terminals
Parent topic: Configuring CICS Terminals and Printers


Defining Terminal Models

The steps to define a terminal model are outlined below.

  1. Create a new entry in the terminal control table. (In ESMAC select Resources > by Type, click one of the table buttons, scroll down to the end of the table, and click Term.)
    • For a terminal definition specified as Model: Only, you must specify:
      • Model Name.
      • Terminal Type: the name of a typeterm entry
    • For a terminal definition specified as Model: Yes, you must specify:
      • Model Name.
      • Terminal Type: the name of a typeterm entry
      • Net Name.
    • A terminal definition specified as Model: No is a physical terminal definition and you must specify:
      • Terminal Type: the name of a typeterm entry
      • Net Name.
  2. Create a matching T-Type entry (if none exists). (In ESMAC from the Term page click Group List, scroll down to the end of the table, and click TType.) At a minimum, this must specify:
    • Def. Screen Height
    • Def. Screen Width

    Many different models can refer to the same T-Type entry.

Parent topic: Configuring CICS Terminals and Printers


Enabling CICS Printer Support

You can use a printer device for 3270 printer support. Printer support is handled by 3270 printer emulators, which interpret the 3270 printer data stream and send it to a system printer.

Use the printer exit program DFHUPRINT to redirect printed output to different print type 3270 devices with multiple physical printers or print spooler queues.

DFHUPRINT must reside on the transaction path for your enterprise server. The exit program is called during the processing of 3270 printed output after a SEND with PRINT event. These events are buffered and result in an OPEN call, a number of PRINT calls, and a CLOSE call.

When the OPEN call is made, the control block contains the terminal ID of the target 3270 print device. You can use this ID to identify the target system printer through a table, for example.

An extract from the exit program is shown below.

       open-printer section.
           evaluate true
               when upi-printer-termid = 'L860'
                    string '\\nwb-savprint' delimited by size
                           '\training-hp4v' delimited by size
                      into ws-filename
                    end-string
               when upi-printer-termid = 'L861'
                    string '\\nwb-savprint' delimited by size
                           '\training-hp5v' delimited by size
                      into ws-filename
                    end-string
               when upi-printer-termid = space
                    move 'Win2PDF' to ws-filename
           end-evaluate
        open extend print-file

If you only have one destination printer, instead of using DFHUPRINT you can start a printer emulator by configuring the following fields on the SIT page in ESMAC:

Field | Contents
3270 Print | Y
Print Destination | Device name for printed output
Note: Regardless of whether you use DFHUPRINT or not, the 3270 Print field must be defined as Y if you want to enable CICS printer support.

The enterprise server then starts a printer emulator for each entry in the terminal table which is:

  • Set as MODEL=NO (the netname must be defined)

    The netname defined in the terminal table must be unique to the region. The terminal ID for the printer is taken from the terminal definition. To avoid conflicts with automatically assigned netnames, you should assign netnames to printers counting downwards from PRNZZZZ.

  • Has a Terminal Type entry which specifies a 3270 printer (3270P)
Parent topic: Configuring CICS Terminals and Printers


Configuring the Autoinstall Exit

The supplied autoinstall exit DFHZATDX selects the best model definition match based on screen size. If you write your own autoinstall program you can select the model and change other parameters such as the terminal ID.

Note: DFHZATDX is not a supplied program. It is a special name that drives the auto-installation behavior.
  • Implementing the Autoinstall Exit Program
  • Autoinstall Interface
Parent topic: Configuring CICS Terminals and Printers


Implementing the Autoinstall Exit Program

To implement autoinstall in a region you can use the supplied autoinstall exit DFHZATDX or you can specify your own autoinstall control program (ACP).

To use your own ACP you must:

  1. Write an Autoinstall Control Program (ACP).

    The interface to ACP is fully defined in the section Auto Control Program Call Interface. Put the executable file for the program on the program path. The Autoinstall Processing section describes the flow of information between the ACP and a CICS Option region.

  2. Enter the ACP program name in the Auto Install Exit field in the SIT.

    Information on updating the SIT . You should be aware that the autoinstall exit interface is designed to be an ASCII interface. The autoinstall exit you specify in the Auto Install Exit field in the SIT must be a program compiled with the CHARSET(ASCII) Compiler directive.

  3. Define one or more terminal models from which the ACP can select
Parent topic: Configuring the Autoinstall Exit


Autoinstall Interface

The ACP is supplied with:

  • Default installation parameters
  • A list of compatible terminal models

The ACP program returns:

  • A single terminal model name
  • A terminal ID
  • A printer ID
  • An alternate printer ID
  • A status byte, which must be set to LOW-VALUES. If not, the terminal is not installed.
Parent topic: Configuring the Autoinstall Exit


Autoinstall Control Program Call Interface

The ACP has the following call interface:

ENTRY ai-prog-name USING a-string pointer-1 pointer-2
       pointer-3 pointer-4

where:

ai-prog-name
is the program name entered in the Auto Install Exit field of the SIT.

The remaining parameters are part of DFHCOMMAREA as follows:

01  DFHCOMMAREA
    03 a-string     PIC X(4).
    03 pointer-1    POINTER.        pointing to Net-Info.
    03 pointer-2    POINTER.        pointing to Model-table.
    03 pointer-3    POINTER.        pointing to TCT-Info.
    03 pointer-4    POINTER.        pointing to Term-Info.

where:

a-string
contains x'F0' in the first byte. If the autoinstall exit is to reject the install attempt, the ACP should not alter this value. If the autoinstall exit is to accept the install attempt, the ACP should set a-string to LOW-VALUES.
pointer-n
is defined further in the following sections, pointer-1, pointer-2, pointer-3 and pointer-4.

This data format and those for pointer-1, pointer-2, pointer-3, and pointer-4 are supplied in copybook dfhcwai.cpy.

  • pointer-1
  • pointer-2
  • pointer-3
  • pointer-4
Parent topic: Configuring CICS Terminals and Printers


pointer-1

pointer-1 points to memory block 1.

Data Format:

Memory block 1 is passed to the ACP with data in the following format:

01  Net-info.
    03 name-length      PIC X       COMP-X.
    03 netname          PIC X(8).

where:

name-length
contains the length of the netname field.
netname
contains the netname, this field is padded with spaces to eight characters.
Parent topic: Autoinstall Control Program Call Interface


pointer-2

pointer-2 points to memory block 2.

Memory block 2 is passed to the ACP containing the list of suitable autoinstall models for the physical screen.

Data Format:

01  Model-table.
    03 table-name-count     PIC X    COMP-X.
    03 autinst-name-1       PIC X(8).

You can include between 1 and 100 entries of autinst-name-n, depending on table-name-count.

where:

table-name-count
is the number of entries in the table
autinst-name-n
in the autoinstall model name.

The memory block contains table-name-count autoinstall entries.

Parent topic: Autoinstall Control Program Call Interface


pointer-3

pointer-3 points to memory block 3. The ACP uses memory block 3 to return information enabling CICS support to create a TCT entry and log the terminal on to the system.

Data Format:

01 TCT-Info.
    03 autinstname          PIC X(8).
    03 terminal-id          PIC X(4).
    03 printer-id           PIC X(4).
    03 altprinter-id        PIC X(4).
    03 status-byte          PIC X(1).

where:

autinstname
is the name of the autoinstall model to be used to create the terminal.
terminal-id
is the ID with which CICS support registers the terminal. If the ID is set to LOW-VALUES, CICS support assigns an ID automatically. CICS support terminal ids are assigned from A0000, B0000... to Z9999.
printer-id
is the printer to assign to the terminal. If set to LOW-VALUES, CICS support assigns the printer defined for the autoinstall model.
altprinter-id
is the printer to assign to the terminal. If set to LOW-VALUES, CICS support assigns the alternate printer defined for the autoinstall model.
status-byte
set this byte to LOW-VALUES to register the terminal. If set to any other value, CICS support aborts terminal registration.
Parent topic: Autoinstall Control Program Call Interface


pointer-4

pointer-4 points to memory block 4.

Data Format:

Memory block 4 contains data in the following format:

01 Term-Info.
    03 term-info-length     PIC X   COMP-X.
    03 height               PIC X   COMP-X.
    03 width                PIC X   COMP-X.
    03 uctran-setting       PIC X.

where:

term-info-length
is the length of following control block. In this release, always contains 3.
height
is the height of physical display in rows.
width
is the width of physical display in columns.
uctran-setting
contains U if uppercase translation was enabled on the Configure Default 3270 Terminal dialog box.
Parent topic: Autoinstall Control Program Call Interface


Autoinstall Processing

This section explains the process and information flows when a user starts a 3270 terminal emulator from the Enterprise Developer IDE.

Figure 1. The autoinstall process

  1. The autoinstall process receives information from the terminal installation parameters.
  2. The autoinstall process builds a list of models (from resource definitions in the terminal control table), with screen sizes compatible with the physical terminal.
  3. The autoinstall process calls the ACP, supplying it with the following information:
    • The list of autoinstall model names
    • The physical screen size
    • The netname
    • A suggested terminal ID (last four characters of the netname)
    • Whether or not UCTRAN was set
  4. The ACP returns the parameters that CICS support needs to create a terminal control table entry dynamically. These are:
    • Terminal ID
    • Terminal model name

    The ACP also supplies the name of a printer and alternate printer to be associated with the terminal.

  5. CICS support dynamically creates a terminal control table entry, using the returned parameters and the terminal model definition.
Parent topic: Configuring CICS Terminals and Printers


CICS Web Interface Support

Enterprise Server with Mainframe Subsystem Support with CWI support enables a CICS region to act both as an HTTP server and as an HTTP client.

CWI applications require the creation of the following resources:

  • TCPIPSERVICE resource definition for each port that your applications use for CICS web support.
  • URIMAP resource to specify how HTTP requests are to be processed.

Enterprise Server supports CICS Transaction Server version 3.1 and later.

  • To enable CICS Web interface support
    This task enables you to run Web-aware CICS programs.
  • CICS Web Error Processing
    Sources and copybooks that enable you to perform error processing for Web-aware applications.
  • Analyzer Programs
Parent topic: CICS Support


To enable CICS Web interface support

  1. Start ESMAC for your enterprise server region.
  2. Create a TCPCICPService for each port targeted by http requests. The Enterprise Server communication layer dynamically starts a listener on each port.
    Important: If you are using a secured region using an MLDAP ESM, be sure the user ID has permission to access to the following resources:
    • CWXN

      This is the alias transaction specified in the default TCPIPSERVICE definition. If you have replaced the default definition, be sure the user ID has permission to run the replacement transaction.

    • CWBA
    • The PPT for the CICS program you want to run
Parent topic: CICS Web Interface Support


CICS Web Error Processing

  • Web Error Application program
  • Web Error Program
Parent topic: CICS Web Interface Support


Web Error Application program

DFHWBERX uses the EXEC CICS WEB and DOCUMENT API commands to get information about the Web client's request and create and send the error response.

DFHWBERX is used in the following circumstances:

  • When it is configured in the Program setting in a URIMAP definition, if an error response is always wanted for the request.
  • When the default analyzer program DFHWBAAX is set as the analyzer program on the TCPIPSERVICE definition, and no matching URIMAP definition is found for a request. DFHWBAAX sets DFHWBERX as the application program using the wbra_server_program output parameter.

Refer to IBM's CICS Transaction Server documentation for more details of how DFHWBERX processes errors and recommendations on how to use it.

Parent topic: CICS Web Error Processing


Web Error Program

The Web error program DFHWBEP receives a list of parameters containing error information, and a block of storage containing the default HTTP response to send to the Web client. The program can use or modify the default response, or create and send its own response using the EXEC CICS WEB and DOCUMENT API commands.

The error information passed to DFHWBEP includes an HTTP status code, an error code, abend code, message number, response and reason codes, and the name of the program where the error has occurred. You can modify all the items in the error response.

Refer to IBM's CICS Transaction Server documentation for guidelines and recommendations on how to use DFHWBEP, and descriptions of the input and output parameters it uses.

Parent topic: CICS Web Error Processing


Analyzer Programs

Analyzer programs are associated with TCPIPSERVICE definitions. They interpret selected HTTP requests and take over some of the processing, monitoring and audit actions normally performed by a URIMAP.

Each CICS Web support TCPIPSERVICE definition must use an analyzer program, and each TCPIPSERVICE definition can specify a different analyzer program.

The use of an Analyzer program is specified in the Analyzer field of URIMAP definition and can override the URIMAP's Convertor, Transaction, User Id, and Program options when used.

Important:
  • You can only use analyzer programs if they have been compiled with ASCII specified as the character set.
  • Analyzer programs can only be called when CICS is an HTTP server. You cannot use them if CICS is an HTTP client, or processing Web services.

The Default Analyzer

If no URIMAP is defined, or no value is entered in the Analyzer field of a URIMAP definition, Enterprise Server uses DFHWBAAX as the default analyzer program for TCPIPSERVICE definitions that have Protocol set to "HTTP".

DFHWBAAX tests for the presence of a URIMAP definition, and depending on the result performs the following:

  • If it finds a URIMAP definition, DFHWBAAX automatically accepts the URIMAP definition's Transaction (alias transaction), Converter (converter program), and Program (application program) settings for use in any further processing.
  • If it does not find a matching URIMAP definition, DFHWBAAX passes control to the Web error application program DFHWBERX to produce an error response. For this to happen you must configure DFHWBERX as the application program to handle the request using the wbra_server_program output parameter.

For more information on DFHWBAAX and how to use TCPIPSERVICE analyzer programs, see IBM's CICS Transaction Server documentation.

Parent topic: CICS Web Interface Support


Transaction class (TRANCLASS) support

Transaction classes give you a mechanism to limit the number of CICS tasks in your system. By spreading your tasks across a number of transaction classes, and controlling the maximum number of tasks that can be dispatched within each transaction class, you can control resource contention between tasks, and limit the number of tasks that CICS considers eligible for dispatching at task attach.

Use the MaxActive attribute of the transaction class definition (TRANCLASS) to control a specific set of tasks that are heavy resource users, tasks of lesser importance (for example, "Good morning" broadcast messages), and so on, allowing processor time or storage for other tasks. Together with the number of SEPs configured (effectively the MXT system initialization parameter equivalent), transaction classes control the transaction mix, that is, ensuring that one type of transaction does not monopolize CICS. In particular, you can restrict the number of heavyweight tasks. For example, you can use transaction classes to isolate tasks, or put all user tasks into separate classes. Suggested classes are simple inquiries, complex inquiries or short browses, long browses, short updates, long updates. Separate non-conversational tasks from conversational tasks. If you need to single-thread non-reentrant code, we suggest you use ENQ.

Using transaction classes can be useful for tasks that consume particularly large amounts of resource, but that do not frequently exceed the MaxActive ceiling. Do not use transaction classes for normal tasks or for design reasons such as serializing a function within a particular task. Application design should be reviewed as an alternative in these cases.

Transaction class support is switched off by default. To activate it, assign the value Y to the environment variable ES_TEST_TRANCLASS.

To take advantage of these capabilities, you must create a TRANCLASS resource type and then add a reference to it in PCT definition(s) of the transactions, the execution of which is to be managed. See the Help for details of resource definition.

Parent topic: CICS Support


Modernizing CICS Applications

This chapter provides information about how you can extend your existing CICS applications.

  • Overview
  • Access to CICS Programs from Web Services and Services called from EJBs
  • CICS Transaction Gateway
  • Data Conversion
Parent topic: CICS Support


Overview

Extending existing applications involves the process of exposing your CICS applications to a range of non-CICS client types. Enterprise Server provides the following extension facilities:

  • Access to CICS programs from Web services and Enterprise JavaBeans running under Enterprise Server. For this you need no extra software.
  • CICS Transaction Gateway. For this you need IBM CICS Transaction Gateway (CTG) or IBM Universal Client. A typical scenario is where a graphical front-end runs on a PC, possibly in a Web browser, and uses a CICS application to access data resources managed by Enterprise Server.
Parent topic: Modernizing CICS Applications


Access to CICS Programs from Web Services and Services called from EJBs

A COBOL program running as a service in an enterprise server can call a CICS program running in the same enterprise server. The service can be either a Web service or a service called from an EJB. The service must be configured to be container-managed.

To use this facility you need to:

  1. Code an EXEC CICS LINK statement in the COBOL source program.
  2. Compile it using an extra Compiler directive option.
  3. Deploy the program in the usual way, having carried out any interface mapping required to make the program accessible as a service to client programs.
  4. Run the program as a service in an enterprise server. This involves invoking it from a suitable client.
  • Coding the EXEC CICS LINK Statement
  • Compiling the COBOL Program
  • Deploying the COBOL Program
  • Running the Service in an Enterprise Server
  • Restrictions
Parent topic: Modernizing CICS Applications


Coding the EXEC CICS LINK Statement

The COBOL program calls the CICS program using the External CICS Interface (EXCI). To use this interface, you need to code an EXEC CICS LINK call every time the COBOL program wants to invoke a CICS program.

CAUTION:
An EXCI call can only be executed in a service that is Container Managed. An EXCI call executed in an Application Managed generates an abend: EXIA.

This is similar to the EXEC CICS LINK call used in a CICS program to perform distributed program linking. However, there are some significant differences.

The format of the call is as follows:

EXEC CICS LINK
    PROGRAM(program-name)
    RETCODE(data-area-1)
    COMMAREA(data-area-2)
    .
    .
    .
    END-EXEC

where the options are as follows:

PROGRAM(program-name) | The name of the CICS program to be invoked
RETCODE(data-area-1) | An area in which the CICS program places a return code indicating sucess or failure
COMMAREA(data-area-2) | An area that the service program and the CICS program use for communications

The call must be immediately followed by an EXEC-END statement.

For example:

exec cics link
               program     (ws-program)
               commarea    (ws-commarea)
               retcode     (exci-exec-return-code)
end-exec

We supply a copy book, dfhxcplo.cpy, which provides data descriptions for RETCODE and COMMAREA. You can find this copybook in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib . The copybook has data descriptions for the parameter passed in the RETCODE field, exci-exec-return-code:

01 exci-exec-return-code.
   03 exec-resp                pic 9(8) comp.
   03 exec-resp2               pic s9(8) comp.
   03 exec-abcode              pic x(4).
   03 exec-msg-len             pic 9(8) comp.
   03 exec-msg-ptr             pointer.
Parent topic: Access to CICS Programs from Web Services and Services called from EJBs
Related information
CICS External CICS Interface Guide


Compiling the COBOL Program

You need to compile the program in Enterprise Developer with the CICSECM(EXCI=YES) directive.

Parent topic: Access to CICS Programs from Web Services and Services called from EJBs


Deploying the COBOL Program

After you have performed any interface mapping necessary to make the program available as a service, you need to deploy it. For more information on interface mapping and deploying, see the Service Interfaces part of the help. The program must be deployed as a container-managed service.

Parent topic: Access to CICS Programs from Web Services and Services called from EJBs


Running the Service in an Enterprise Server

Once the COBOL program has been deployed to the MSS-enabled enterprise server where the target CICS program runs, you need to invoke it using a suitable client.

When the EXEC CICS LINK statement in the service program is executed, control is passed to the CICS program, which executes and passes the results back to the calling service program. The service program sets the return code to indicate to the container whether or not the transaction should be rolled back.

When a service executes within an enterprise server, the COBOL program search path is restricted to the setting of Package Path within the service’s package object, set on the Edit Package page of Enterprise Server Adminstration. When an EXCI call is issued, the search path is temporarily modified to include the system-wide CICS Transaction Path set on the Edit Server > Properties > MSS page.

Parent topic: Access to CICS Programs from Web Services and Services called from EJBs


Restrictions

The following restrictions apply to the use of the External CICS Interface:

  • The COBOL service and the CICS program it calls must be running in the same enterprise server. The EXEC CICS LINK command takes the APPLID() operand, which is used to specify a remote server on which the CICS program resides, but it is ignored.
  • The EXEC CICS LINK command takes the SYNCONRETURN() operand, which is used to specify that the MSS enterprise server is to take a syncpoint on successful completion of the server program. This operand is ignored. You can only use the EXCI interface from a container-managed service. The resources updated by the CICS program should not be committed or rolled back until the container-managed service is complete so that the CICS resources remain coordinated with those of the calling service.
  • The CICS program should not issue explicit EXEC CICS SYNCPOINT commands. Results will be unpredictable and might leave resources in an inconsistent state.
Parent topic: Access to CICS Programs from Web Services and Services called from EJBs


CICS Transaction Gateway

CTG is middleware that permits non-CICS client programs to interoperate with CICS applications running on Enterprise Server. In this context, the abbreviation CTG is used to mean IBM CICS Transaction Gateway or IBM Universal client.

The CTGDEMO sample application demonstrates how CTG can be employed as the middleware to enable client ECI or EPI programs to interact with a server-based CICS application.

Parent topic: Modernizing CICS Applications


Data Conversion

Within a single system using MSS, file data is always presented in the same codeset in which it was recorded. Between two systems running MSS, or between MSS and other CICS systems, data may need to be translated between EBCDIC and ANSI. The requirement and the method you use to meet it depend on which middleware you are using.

  • If You Use CICS Transaction Gateway
Parent topic: Modernizing CICS Applications


If You Use CICS Transaction Gateway

If you use IBM CICS Transaction Gateway, you can supply information that enables data to be converted in data conversion templates, which are held in an indexed file called dfhdrcnv, in the same folder as the resource definition file (by default ). Each data conversion template contains entries for resources that need translation and identifies which data fields require it. Each resource must have an entry in the resource definition file.

You cannot edit the file dfhdrcnv directly; instead you maintain it by importing mainframe-style DFHCNV macros, and by deleting templates that you no longer need.

Mainframe-style DFHCNV macros are organized into entries and templates. An entry is a set of conversion macros that apply to the same resource; the start of an entry is marked by a DFHCNV macro that begins TYPE=ENTRY and the entry continues until the next macro that begins TYPE=ENTRY, or until the END marker. An entry can contain one or several templates, depending on the type of resource it belongs to.

  • Importing Data Conversion Templates
  • Example Macros
Parent topic: Data Conversion
Related information
CICS Family: Communicating from CICS on System/390
CICS Web Interface Guide CICS for MVS/ESA 4.1


Importing Data Conversion Templates

You use the command cascnvim to import the data conversion templates. For more information see the help topics cascnvim and Data Conversion.

Note:

If data conversion is required for a program's COMMAREA, you must define a PPT entry for that program; see the section Controlling CICS Resources in the chapter Administering MSS-enabled Enterprise Servers.

Parent topic: If You Use CICS Transaction Gateway
Related information
cascnvim
Data Conversion


Example Macros

The following data conversion macros apply to a file (TESTFC), which has two data constructs, and to a program (TESTPC):

TITLE 'DFHCNV MACRO IMPORT'
* --------- START OF DFHCNV MACROS ---------- *
DFHCNV TYPE=INITIAL,CLINTCP=(932, 437,XXXX)
SPACE 2
DFHCNV TYPE=ENTRY,RTYPE=FC,RNAME=TESTFC,USREXIT=NO
DFHCNV TYPE=KEY
DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=8
DFHCNV TYPE=FIELD,OFFSET=8,DATATYP=PD,DATALEN=3,LAST=YES
DFHCNV TYPE=SELECT,OPTION=COMPARE,OFFSET=11,DATA='A'
DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=8
DFHCNV TYPE=FIELD,OFFSET=8,DATATYP=PD,DATALEN=3
DFHCNV TYPE=FIELD,OFFSET=11,DATATYP=CHARACTER,DATALEN=1
DFHCNV TYPE=FIELD,OFFSET=12,DATATYP=PD,DATALEN=4
DFHCNV TYPE=FIELD,OFFSET=16,DATATYP=PD,DATALEN=4
DFHCNV TYPE=FIELD,OFFSET=20,DATATYP=BINARY,DATALEN=8
DFHCNV TYPE=FIELD,OFFSET=28,DATATYP=USERDATA,DATALEN=10, X23456789
USRTYPE=B'01010000'
DFHCNV TYPE=FIELD,OFFSET=38,DATATYP=CHARACTER,DATALEN=50, X
LAST=YES
DFHCNV TYPE=SELECT,OPTION=COMPARE,OFFSET=11,DATA='B'
DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=8
DFHCNV TYPE=FIELD,OFFSET=8,DATATYP=PD,DATALEN=3
DFHCNV TYPE=FIELD,OFFSET=11,DATATYP=CHARACTER,DATALEN=1
DFHCNV TYPE=FIELD,OFFSET=12,DATATYP=USERDATA,DATALEN=2
DFHCNV TYPE=FIELD,OFFSET=14,DATATYP=CHARACTER,DATALEN=20, X
LAST=YES
DFHCNV TYPE=ENTRY,RTYPE=PC,RNAME=TESTPC
DFHCNV TYPE=SELECT,OPTION=DEFAULT
DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=BINARY,DATALEN=12
DFHCNV TYPE=FIELD,OFFSET=12,DATATYP=CHARACTER,DATALEN=96
DFHCNV TYPE=FINAL
END
Parent topic: If You Use CICS Transaction Gateway


Administering CICS-enabled Enterprise Servers

This chapter describes how you can use Enterprise Server Monitor and Control to run CICS applications.

  • Overview
  • Visual Appearance
  • Enabling MSS for an Enterprise Server
  • Changing the SIT for an MSS-Enabled Server
  • Configuring CICS Search Paths
  • Specifying a Listener for TN3270 Terminals
  • Sending Messages to All Terminals
  • Viewing Locks
  • Controlling CICS Resources
Parent topic: CICS Support


Overview

Enterprise Server Monitor and Control (ESMAC) enables you to monitor and control CICS-enabled enterprise servers. When Enterprise Server is being used to run CICS applications, an enterprise server corresponds to a CICS region. You can use ESMAC to ensure all the resources required by your CICS application are available, and change and create resources for your application and other applications as necessary. You can also use all the facilities described in the chapter Administering Servers Using ESMAC in your Enterprise Server Configuration and Administration Guide, and in the help topics grouped under Administer a Server Using ESMAC. You should familiarise yourself with the contents of that chapter and the associated help topics before reading this chapter.

Parent topic: Administering CICS-enabled Enterprise Servers
Related information
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 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


Visual Appearance

When you first view ESMAC for an CICS-enabled enterprise server, the Server Information page is displayed, as shown in Figure 0-1 :

Figure 1. ESMAC Server information page for CICS
ESMAC Server information page for CICS

When you run ESMAC on an CICS-enabled enterprise server, you can use it to view and change SITs, groups, startup lists, and other CICS resources required by CICS applications running on the enterprise server, in addition to all the facilities ESMAC provides for servers that are not enabled for CICS.

Parent topic: Administering CICS-enabled Enterprise Servers


Enabling MSS for an Enterprise Server

You enable MSS on an enterprise server in the same way on both Windows and UNIX.

To enable MSS, you use Enterprise Server Administration (for an introduction to this tool, see the chapter Introduction to Enterprise Server Administration in your Enterprise Server Configuration and Administration Guide).

Note: You need the appropriate license before you can use an MSS-enabled enterprise server.
  • To enable MSS for an existing enterprise server
Parent topic: Administering CICS-enabled Enterprise Servers
Related information
To enable MTO for an enterprise server
Introduction to Enterprise Server Administration


Changing the SIT for an MSS-Enabled Server

If you want to change the SIT that is associated with an MSS-enabled enterprise server, you have to return to the Home page of Enterprise Server Administration, stop the server, edit the server's Properties > MSS page, start the server and return to ESMAC.

  • To change the SIT associated with a server
Parent topic: Administering CICS-enabled Enterprise Servers
Related information
To change the SIT associated with a server


Configuring CICS Search Paths

You can also use the Properties > MSS page to configure CICS search paths. You can define the paths to the directories that contain CICS application programs, CICS BMS load modules, the CICS resource definition file, and the default location for CICS VSAM data sets.

  • To configure CICS search paths
Parent topic: Administering CICS-enabled Enterprise Servers
Related information
To configure CICS search paths


Specifying a Listener for TN3270 Terminals

Enterprise Server MSS provides support for TN3270 clients. To enable the TN3270 client support you need to define a new listener in Enterprise Server Administration.

  • To specify a listener for TN3270 terminals
Parent topic: Administering CICS-enabled Enterprise Servers
Related information
To specify a listener for TN3270 terminals


Sending Messages to All Terminals

ESMAC provides a facility for sending a message to all the 3270 clients currently connected to the server.

  • To send a message to all 3270 terminals
Parent topic: Administering CICS-enabled Enterprise Servers
Related information
To send a message to all 3270 terminals


Viewing Locks

You can view the current locks that have been issued against resources such as files.

  • To view resource locks
Parent topic: Administering CICS-enabled Enterprise Servers


Controlling CICS Resources

ESMAC enables you to view, create and modify the resources required by a CICS application running on an enterprise server. An enterprise server equates to a CICS region. When a CICS region starts, it is typically initialized with a system initialization table (SIT). The SIT defines various startup parameters, as well as defining which startup lists are invoked. The startup lists define which groups are used by the CICS applications in this region. The groups in turn define the resources (for example, file control tables and program processing tables) to be loaded for use by applications.

You can maintain the following resources

  • SITs
  • Startup lists
  • Groups
  • Tables

This includes not just the resources used by this enterprise server, but all the resources defined in the resource definition file for this enterprise server.

ESMAC provides flexibility in the way you view resources. You can view:

  • Active resources - the resources that are currently active on the enterprise server. An enterprise server is associated with a SIT, and when the SIT is initialized, it invokes its startup list, which contains the groups in which resources are stored. These then become active.

    The Active resources category includes two items that are not strictly speaking resources:

    • ICE, which stands for interval control elements, CICS-related events that are scheduled to happen in the future
    • Resource locks
  • Resources by group - the resources in groups currently defined in the enterprise server's resource definition file.
  • All the SITs in the resource definition file.
  • All the startup lists in the resource definition file.
  • Resources used by the current startup list - resources defined in groups that are defined in the startup list initiated by the SIT for the enterprise server.
  • Resources by type - all resources, listed according to type (FCT, DCT, and so on).
  • Detailed information for any resource.

If you have suitable permissions you can also:

  • Modify resources.
  • Delete resources.
  • Create new resources, such as tables and groups. You can do this in two ways:
    • Create a new resource using the values of an existing resource.
    • Create a completely new resource. How you do this depends on whether you are creating a new table (FCT, DCT, and so on) or another resource (such as a group or SIT).
  • Format and view a dump of a resource.
  • Delete interval control elements and data queues
  • To view active resources
  • To view and delete data queue items
  • To view detailed information for a resource
  • To view and delete interval control elements
  • To create a resource from an existing resource
  • To view resources by group
  • To view resources by startup list
  • To view resources by type
Parent topic: Administering CICS-enabled Enterprise Servers
Related information
To view active resources
To view resources by group
To view resources by startup list
To view resources by type
To view detailed information for a resource
To view and delete data queue items
To view and delete interval control elements
To view resource locks
To create a resource from an existing resource
To create a resource table
To create a resource group
To delete a resource
To view a dump of a resource
To create a SIT
To create a startup list
To change the SIT associated with a server


MSS Aspects of Troubleshooting

This chapter covers some aspects of troubleshooting problems with running applications in an Mainframe Subsystem Support(MSS)-enabled enterprise server.

  • Introduction
  • Configuring Dumps for Data Capture
  • Viewing a System Trace
Parent topic: CICS Support


Introduction

Problem diagnosis on an MSS-enabled enterprise server is very similar to problem diagnosis on an enterprise server running Web services or EJB-type services, as described in the chapter Troubleshooting in the Enterprise Server Configuration and Administration Guide.

Parent topic: MSS Aspects of Troubleshooting


Configuring Dumps for Data Capture

When you are configuring dumps and traces for an MSS-enabled enterprise server, you might want to select dump on transaction abend; on the ESMAC Control page click Tran next to Dump on ABEND. Dumps created when transactions abend are internally triggered dumps. When you do your data capture, you should include the transaction abend dump, if one exists.

There is a fourth way of obtaining an externally triggered dump: issue an EXEC CICS DUMP command in a CICS program.

Parent topic: MSS Aspects of Troubleshooting


Viewing a System Trace

On the Trace page of ESMAC, which you see when you request a trace from the Diagnostics group in the menu, the process IDs that appear in the PIDs column can have the following additional prefixes:

3 | 3270 client
L | CCI listener
Q | WebSphere MQ listener

The prefix J for journal control also covers extra-partition transient data

Parent topic: MSS Aspects of Troubleshooting


JCL Support

  • Configuring Enterprise Servers for JCL
  • Administering JCL-enabled Enterprise Servers
  • z/OS Enterprise Server Extensions
    Describes the Enterprise Server extensions designed to enhance usability, performance, and to allow more granular control.
  • Configuring JCL Timeouts
  • JCL Aspects of Troubleshooting
  • JCL Support Tasks
Parent topic: MSS Configuration and Administration


Configuring Enterprise Servers for JCL

This chapter describes how to create and configure JCL-enabled enterprise servers.

  • Enabling JCL for an Enterprise Server
  • SEPs for JCL
  • Shared Memory Area
  • Environment Validation
  • Spool Housekeeping
  • Running the Spool Housekeeping Program from JCL
  • Controlling where Datasets are Created
  • Separating the Spool Files From the Main Catalog File
  • Restarting Jobs
Parent topic: JCL Support
Related concepts
Creating and Configuring an Enterprise Server Instance for IMS


Enabling JCL for an Enterprise Server

You enable JCL on an enterprise server in the same way for both Windows and UNIX by using Enterprise Server Administration (for an introduction to this tool, see the chapter Introduction to Enterprise Server Administration in your Enterprise Server Configuration and Administration Guide ).

Note: You need the appropriate license before you can use an JCL-enabled enterprise server.
  • To enable JCL support
  • To enable MSS for an existing enterprise server
Parent topic: Configuring Enterprise Servers for JCL
Related information
To enable MTO for an enterprise server
To enable JCL support


SEPs for JCL

Two special types of service execution process are required to run JCL jobs. These are:

  • Batch initiator SEPs. A batch initiator SEP runs jobs.
  • Batch printer SEPs. A batch printer SEP handles the sending of output to a printer.

Both types of SEP have a class property. The JOB CLASS of a JCL jobstream must match the class of a batch initiator SEP in order for the SEP to run the job. The MSGCLASS or SYSOUT class must match the class of a batch printer SEP in order for the SEP to print the output.

You can either define permanent batch initiator and printer SEPs or create SEPs during a session that exist only until the end of the session.

When you define a batch printer SEP, you can specify a printer exit module, which enables you to perform additional formatting of output data before it is printed. For more information see the section Printer Exit Modules in the chapter JCL Support in your MTO Developer's Guide, if you have the development documentation available.

If you want to create a batch printer SEP that uses a printer accessed across a network, you need to have started the enterprise server from the command line or from the IDE; if you start it from ES Admin, it runs as a system service and the network printers defined on your machine are not available.

  • To define a batch initiator or printer SEP
Parent topic: Configuring Enterprise Servers for JCL


Shared Memory Area

The shared memory area calculation for a JCL-enabled enterprise server is the same as for a Web services enterprise server. You must include your batch initiator and batch printer SEPs in the total number of service execution processes.

If you also run CICS applications in the same enterprise server, you will also need to perform the calculations described in the section Shared Memory Area in the chapter Configuring MSS-enabled Enterprise Servers for CICS and add the results to the total.

Parent topic: Configuring Enterprise Servers for JCL


Environment Validation

When you start an enterprise server, a utility called DFHZJCL2 runs automatically to check for some common set-up errors that might otherwise be hard to spot. For example, it checks that the system catalog and default allocation location are both usable. If a problem is found, it displays a message on the console log.

For example, should the catalog be unusable there will be a message in the log saying: "Catalog Open IVP test failed".

Once it has completed the validation DFHZJCL2 schedules the spool housekeeping by issuing a CICS START for transaction JCL1.

Parent topic: Configuring Enterprise Servers for JCL


Spool Housekeeping

There are two JCL utility programs available to perform spool housekeeping. Both perform similar functions, but are configured in different ways.

MVSP0027
MVSP0027 is a JCL utility program that removes all spool files and job records for jobs that have exceeded the maximum retain period. For the remaining jobs, it removes the spool files from the OUT HOLD queue.
To change any of the settings, such as the retention period, you must edit the copybook (spoolhk.cpy), and then recompile the program that uses it (DFHZJCL3).
MVSSPLHK
MVSSPLHK is a JCL utility program that performs the same functions as MVSP0027, and also provides enhanced archiving facilities. This utility can be run directly from a JCL job, with the configuration settings held in a file or as in-stream data. This means that you do not need to recompile anything when you change any of the configuration settings.

You can also further configure how either housekeeping utility is run using a number of environment variables.

  • MVSP0027 Spool Housekeeping Process
  • MVSSPLHK Spool Housekeeping Process
  • Spool Housekeeping-specific Environment Variables
  • Spool Housekeeping Return and Reason Codes
Parent topic: Configuring Enterprise Servers for JCL


MVSP0027 Spool Housekeeping Process

When you start an enterprise server, a CICS transaction called JCL1 runs to delete old spool files. You can configure how often this happens and how long spool files are kept for.
Note: This process does not run automatically. You need to configure it using the PTLPI process. You also need to configure the CICS region to use spool housekeeping. SSTM is mandatory to enable support for the spool queue.

The housekeeping process involves the following programs: DFHZJCL1, DFHZJCL3, MVSP0027. The validation program described in the previous section starts the transaction JCL1, which runs the program DFHZJCL1. This program does the following:

  • LINKS to DFHZJCL3 to get the Housekeeping Frequency (i.e. how often spool housekeeping should be run) and the Housekeeping Retain Period (i.e. how long spool files should be kept prior to automatic deletion).
  • CALLS MVSP0027 passing the Housekeeping Retain Period. MVSP0027 deletes any spool files older than the retain period.
  • STARTS JCL1 after the interval specified in Housekeeping Frequency
  • Displays messages on the console saying that the spool housekeeping has:
    • started: SPOOL CLEAN-UP started

      and

    • finished (successfully or not ): SPOOL CLEAN-UP ended normally, maximum retain period is 6 days.
Note:

The preferred way of running Spool Housekeeping is using JCL, as described in this help. The job can then be scheduled to reflect the realities of the customer's environment.

You can also run spool housekeeping using a CICS trancode. To do this:
  • Define the CICS trancode for JCL1 that points to program DFHZJCL1.
To set that this trancode runs automatically upon server startup, add the group that contains that trancode to the startup list.
  • Setting the Retain Periods
  • Setting the Default Retain Period and Run Frequency
  • Setting the Retain Period and Archive Flag for Specific Held Classes
Parent topic: Spool Housekeeping
Related information
MVSSPLHK Spool Housekeeping Process
Spool Housekeeping-specific Environment Variables
Spool Housekeeping Return and Reason Codes


Setting the Retain Periods

You configure the retain periods by editing and recompiling DFHZJCL3, one of the programs run during the housekeeping process.

Note: When you configure a retain period less than the default clean up date, only HELD output is deleted before the default cleanup date. The JESYSMSG spool file is not deleted until the default clean up date is reached regardless of what class it is. Other processes depend on this file while any spool output is retained.

For example, a job produces JESYSMSG and SYSPRINT output to class B. If the retain period for class B is 2 days and the default retain period is 7 days, and class B is HELD, only the SYSPRINT will be deleted after 2 days.

If class B is not HELD, neither spool file is deleted after 2 days. All spool output, including the JESYSMSG regardless of whether HELD or not, will be deleted after 7 days.

DFHJCL3 uses a user modifiable copybook which contains the run frequency and retain period values. The copy book is SPOOLHK.CPY a portion of which is reproduced below. Set the values as required (see below) and recompile DFHZJCL3.

      **********************************************************************************
      *  This copy book controls the spool housekeeping.
      **********************************************************************************
      *      ws-run-frequency
      *          this field controls how often the spool clean-up is run
      *          it is stated in days
      *      ws-keep-for
      *          this field contains the default retention period in days for
      *          spooled output
      **********************************************************************************
           03  default-settings.
             05  ws-version                      pic x(8)
                          value 'SPHK 1.0'.
             05  ws-run-frequency                pic 99999 value 1.
             05  ws-keep-for                     pic 99999 value 6.
      **********************************************************************************
      *    The following fields contain the retention periods for spooled output by class
      *    and a flag indicating whether spool files in this class should be archived on
      *    deletion.  There are 36 entries, A through Z and 0 through 9.
      *    If the value is set to 99999 then the default value from ws-keep-for
      *    will be used. A Y indicates that spool files should be archived upon deletion.
      *    These ws-keep-for values are DAYS.
      *    To change the retention period edit the appropriate values and recompile
      *    DFHZJCL3.cbl
      *    e.g.  to change the class A retention period to 1 week and specify that no
      *    archiving is required:
      *    edit the first  filler for class A so that the value is 7
      *    edit the second filler for class A so that the value is N
      *    giving:
      *      class A
      *      05  filler                           pic 99999 value 00007.
      *      05  filler                           pic x     value 'N'  .
      **********************************************************************************
           03 ws-class-settings.
      *      class A
             05  filler                           pic 99999 value 00001.
             05  filler                           pic x     value 'N'  .
      *      class B
             05  filler                           pic 99999 value 00002.
             05  filler                           pic x     value 'N'  .
Parent topic: MVSP0027 Spool Housekeeping Process
Related information
Setting the Default Retain Period and Run Frequency
Setting the Retain Period and Archive Flag for Specific Held Classes


Setting the Default Retain Period and Run Frequency

The comments in the copybook, SPOOLHK.CPY explain the field values:

 05  ws-run-frequency                pic 99999 value 1
Change the value of ws-run-frequency to the number of days that you want to elapse between runs of spool housekeeping.
Note: The ws-run-frequency value is used only if the spool housekeeping is run using CICS. It has no meaning with the recommended method, that is when you schedule a batch job to run spool housekeeping.
05  ws-keep-for                         pic 99999 value 6

This is the default retain period and applies to ALL spool output, taking precedence over any class-specific retain periods that are greater than this value. It also determines the retain period for JESYSMSG spool files, making it possible to see jobs in the spool job list even when all their other spool files have been deleted due to a shorter class-specific retain period.

Change the value of ws-keep-for to the maximum number of days that you wish to keep spool output for. (This includes: i) Any held output for SYSOUT classes with no specific retain period ii) Any output that was scheduled for printing which is still on the spool print queue)

Note: The retain interval is in days. Using one day is not recommended as a run shortly after midnight would delete spool files written the late previous night; that is, files that are only a few minutes or hours old.
Parent topic: MVSP0027 Spool Housekeeping Process
Related information
Setting the Retain Periods
Setting the Retain Period and Archive Flag for Specific Held Classes
Setting the Retain Periods


Setting the Retain Period and Archive Flag for Specific Held Classes

             05  filler                                 pic 99999 value 99999.
             05  filler                                 pic x     value 'N'  .

For those HELD output classes where the output should be deleted after a SHORTER interval than the above default retain period, edit the first value for the appropriate class.

If you want to archive the contents of the MVS SPOOL spool file prior to deletion, change the second value to ‘Y’ or "J". The file will be copied to the location specified in the environment variable MF_SPOOL_ARCHIVE_LOC. If the value "J" is used, the names of the archive files will be prefixed with the name of the job to which they belong.

Parent topic: MVSP0027 Spool Housekeeping Process
Related information
Setting the Retain Periods
Setting the Default Retain Period and Run Frequency


MVSSPLHK Spool Housekeeping Process

This spool housekeeping process includes enhanced archiving facilities that MVSP0027 does not provide. It can also be run directly from a JCL job.

The parameters for this process are the same as for MVSP0027, but they are stored in a configuration file, which enables you to easily change the parameters from job to job without the need of recompiling anything. You can also specify the parameters within the JCL itself, enabling you to run your housekeeping with settings that override the defaults, at any time.

  • Configuring the MVSSPLHK Housekeeping Process
  • Running the MVSSPLHK Housekeeping Process
  • Sample Parameters File
Parent topic: Spool Housekeeping
Related information
MVSP0027 Spool Housekeeping Process
Spool Housekeeping-specific Environment Variables
Spool Housekeeping Return and Reason Codes


Configuring the MVSSPLHK Housekeeping Process

You can configure certain criteria of the MVSSPLHK housekeeping process. Refer to Sample Parameters File for a sample JCL file that contains some of the parameters listed below:
Parameter specification
You can either specify the parameters in-stream or in a configuration file:
SYSIN DD specifies that the parameters are in-stream.
CONFIGI DD DSN=<dataset> specifies the file in which the parameters are stored.
Output files
You can specify an indexed output file that lists all the files archived by the housekeeping process.
INDEXO DD DSN=<dataset> specifies the file in which a list of the archived files is stored.
You can view this file in ESMAC, or with the aid of the copybook SPLHKARC.CPY, you can read the file and output the details to a location of your choice.
A SYSPRINT file is also produced, which contains additional information about the housekeeping process. It specifies the parameters used, the archive locations, and the actions performed on each archived file.
A SYSOUT DD also displays a summary of the process, including its progress, and any errors displayed via the SYSERR DD.
All these files together provide a comprehensive audit trail for the housekeeping process.
The type of archiving to run
Select one of the following:
NONE
The spool clean-up is performed, but no files are archived.
DATA
The spool clean-up is performed, and only the spool data files are archived
FULL
The spool clean-up is performed, and all files are archived. They are moved to a new directory at the archive location, specified by the MF_SPOOL_ARCHIVE_LOC environment variable. The name of the directory consists of the date and time that the archive ran; a directory of this name should not already exist in order for the housekeeping to run.
FULL, ALL
As FULL.
FULL, HELD
The spool clean-up is performed, and only held data sets are archived.
Setting the retain period
You can specify the default retain period (in days) for the housekeeping process:
MAX-RETAIN-PERIOD 006
sets the default retain period to 6 days.
Override the retain period for individual jobs
You can specify a retain period for individual jobs, overriding the default retain period.
JOB_KEEP XXX* 002
JOB_KEEP BCCRSD35 012
JOB_KEEP YYY*
sets the retain period for any job beginning with XXX to 2 days, sets the retain period for the BCCRSD35 job to 12 days, and keeps any jobs beginning with YYY indefinitely.
Override the retain period for jobs in a particular class
You can specify a retain period for jobs in a particular class, overriding the default retain period.
CLASS A 003 Y
CLASS Z 999 N
sets the retain period for jobs within class A to 3 days, and any older than that are archived, and sets the retain period for jobs in class Z to 999 days (the maximum allowed), and any older than that are not archived.
Override the spool housekeeping run date/time
You can override the date and time that the housekeeping is due to run by setting an environment variable:
MF_SPOOL_HK_TESTDATE=YYYYMMDD
or by passing a parameter to MVSSPLHK when it is invoked:
EXEC PGM=MVSSPLHK,PARM='2014051510303002
sets the spool housekeeping and archiving to run on 05/15/2014 10:30:30:02.
Parent topic: MVSSPLHK Spool Housekeeping Process
Related information
Running the MVSSPLHK Housekeeping Process
Sample Parameters File


Running the MVSSPLHK Housekeeping Process

The following JCL job step demonstrates how to run the MVSSPLHK housekeeping process using parameters stored in an existing data set (TEST.CONFIG):
//ARCHIVE  EXEC PGM=MVSSPLHK
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSERR   DD SYSOUT=*
//INDEXO   DD DSN=TEST.ARCHIVE.XREF,DISP=SHR
//CONFIGI  DD DSN=TEST.CONFIG,DISP=SHR

If a parameter file is specified, any in-stream housekeeping parameters are ignored.

The following JCL job step demonstrates how to run the MVSSPLHK housekeeping process using parameters specified in-stream:

//ARCHIVE  EXEC PGM=MVSSPLHK
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSERR   DD SYSOUT=*
//INDEXO   DD DSN=TEST.ARCHIVE.XREF,DISP=SHR
//* SYSIN or CONFIGI dataset contains the program parameters
//SYSIN  DD *
* --------------------------------------------------------
*   SPOOL HOUSEKEEPING CONFIGURATION FILE
* --------------------------------------------------------
*   GENERAL MAXIMUM RETAIN PERIOD (DAYS)
 MAX-RETAIN-PERIOD 006
* --------------------------------------------------------
*   RETAIN PERIODS FOR SPECIFIC JOB NAMES
 JOB_KEEP   XXX*    001
* --------------------------------------------------------
*   ARCHIVE TYPE REQUIRED
*            NONE,
*            DATA ( SPOOL DATA FILES ONLY )
*            FULL (CASSPOOL, MVSSPOOL AND CATALOG SO SPOOL
*                  ARCHIVES CAN BE VIEWED IN ES. ALL DATASETS ,
*                  HELD, OUTPUT and PRINTED )
*            FULL,ALL (same as ‘FULL’)
*            FULL,HELD (HELD DATASETS ONLY)
* --------------------------------------------------------
 ARCHIVE    TYPE FULL
* --------------------------------------------------------
*   ARCHIVE LOCATION - use the environment variable
*   and append the archive date-time to the location
* --------------------------------------------------------
* ARCHIVE   LOC C:\estest\sphktest\archdir\
* --------------------------------------------------------
*   CLASS SPECIFIC OVERRIDES (PREVIOUSLY IN SPOOLHK.CPY)
*   ONLY INCLUDE THOSE THAT ARE DIFFERENT TO THE MAX-RETAIN-PERIOD
*CLASS ID<SPACE>RETAIN PERIOD<NNN><SPACE>ARCHIVE<Y/N>
*
 CLASS A 003 Y
 CLASS B 003 Y
 CLASS C 003 Y
 CLASS Z 999 Y
* --------------------------------------------------------
/*
Parent topic: MVSSPLHK Spool Housekeeping Process
Related information
Configuring the MVSSPLHK Housekeeping Process
Sample Parameters File


Sample Parameters File

The following is a sample parameters file that you can edit, and then use when running the MVSSPLHK spool housekeeping process.

//SETUP01 JOB 'SPHK',MSGCLASS=A,CLASS=A,MSGLEVEL=(1,1)
//*--------------------------------------------------------
//DEL     EXEC PGM=IEFBR14
//DEL1    DD DSN=TEST.CONFIG,SPACE=(TRK,1),DISP=(MOD,DELETE)
//*==========================================================
//*       CONFIGURATION FILE
//*==========================================================
//DEFCFG   EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *
* --------------------------------------------------------
*   SPOOL HOUSEKEEPING CONFIGURATION FILE
* --------------------------------------------------------
*   GENERAL MAXIMUM RETAIN PERIOD
MAX-RETAIN-PERIOD 003
* --------------------------------------------------------
*   RETAIN PERIODS FOR SPECIFIC JOB NAMES
* --------------------------------------------------------
JOB_KEEP   XXX*    1
* --------------------------------------------------------
*   ARCHIVE TYPE REQUIRED
*            NONE
*            DATA ( SPOOL DATA FILES ONLY )
*            FULL (CASSPOOL, MVSSPOOL AND CATALOG SO SPOOL
*                  ARCHIVES CAN BE VIEWED IN ES. ALL DATASETS,
*                  HELD, OUTPUT and PRINTED)
*            FULL,ALL (same as FULL)
*            FULL,HELD (HELD DATASETS ONLY)
* --------------------------------------------------------
ARCHIVE    TYPE FULL,ALL
* --------------------------------------------------------
*   ARCHIVE LOCATION - use the environment variable
* --------------------------------------------------------
*   ARCHIVE   LOC D:\estest\sphktest\archdir\
* --------------------------------------------------------
*   CLASS SPECIFIC OVERRIDES (PREVIOUSLY IN SPOOLHK.CPY)
*   ONLY INCLUDE THOSE THAT DIFFER FROM THE MAX-RETAIN-PERIOD
*   OR WHERE ARCHIVING IS NOT REQUIRED FOR A CLASS
CLASS A 3 Y
CLASS B 3 Y
CLASS C 3 Y
CLASS D 999 N
CLASS E 999 N
CLASS F 999 N
CLASS G 999 N
CLASS H 999 N
CLASS I 999 N
CLASS J 999 N
CLASS K 999 N
CLASS L 999 N
CLASS M 999 N
CLASS N 999 N
CLASS O 999 N
CLASS P 999 N
CLASS Q 999 N
CLASS R 999 N
CLASS S 999 N
CLASS T 999 N
CLASS U 999 N
CLASS V 999 N
CLASS W 999 N
CLASS X 999 N
CLASS Y 999 N
CLASS Z 4 N
CLASS 0 5 N
CLASS 1 999 N
CLASS 2 999 N
CLASS 3 999 N
CLASS 4 999 N
CLASS 5 999 N
CLASS 6 999 N
CLASS 7 0 N
CLASS 8 999 N
CLASS 9 999 N
* --------------------------------------------------------
//SYSUT2  DD DSN=TEST.CONFIG,SPACE=(TRK,1),UNIT=SYSDA,
//        DCB=(LRECL=80,RECFM=LSEQ,DSORG=PS),DISP=(NEW,CATLG)
//*===========================================================
//*        ARCHIVE XREF FILE
//*===========================================================
//DEFXREF  EXEC PGM=IDCAMS
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  *
    DELETE 'TEST.ARCHIVE.XREF'
    IF MAXCC = 8 THEN SET MAXCC=0
    DEFINE CLUSTER(NAME(TEST.ARCHIVE.XREF)     -
                   KEYS(60 0) -
                   RECSZ(400 400) -
                   INDEXED -
                   SHAREOPTIONS(2 3)       -
                   CYL(40 10))
/*
//*===========================================================
//
Parent topic: MVSSPLHK Spool Housekeeping Process
Related information
Configuring the MVSSPLHK Housekeeping Process
Running the MVSSPLHK Housekeeping Process


Spool Housekeeping-specific Environment Variables

The following environment variables relate to the configuration of the spool housekeeping processes:

Variable Description
MF_SPOOL_ARCHIVE_LOC The base location for files archived as part of the spool housekeeping process.
MF_SPOOL_ARCHIVE_LOC=file-location
MF_SPOOL_HK_LEX_SCAN

Determines if the MFELX* files associated with a job are also deleted when spool housekeeping is run.

MF_SPOOL_HK_LEX_SCAN=Y|N
MF_SPOOL_HK_OUTPRT

Determines if files from the OUTPUT and PRINTED queues are also deleted when spool housekeeping is run.

MF_SPOOL_HK_OUTPRT=Y|N
MF_SPOOL_HK_TESTDATE Overrides the normal date for the spool housekeeping.
MF_SPOOL_HK_TESTDATE=YYYYMMDD
Parent topic: Spool Housekeeping
Related information
MVSP0027 Spool Housekeeping Process
MVSSPLHK Spool Housekeeping Process
Spool Housekeeping Return and Reason Codes


Spool Housekeeping Return and Reason Codes

When you run a spool housekeeping operation, the return code is displayed in the console log, and can be one of the following:

Return code | Explanation
0 | The operation completed successfully without errors.
4 | No spool records were found. You would expect this when a server is first started, if spool housekeeping is scheduled via CICS.
8 | This is a warning, and the processing continues. It indicates that a spool record that was a candidate for deletion could not be deleted (possibly in use), or a catalog entry for a spool record that was a candidate for deletion is not present.
12 | This indicates a configuration parsing error. This code is applicable to the MVSSPLHK housekeeping process only.
16 | This indicates a fatal error. Processing is terminated. Generally, it is the result of an unexpected file status code from IO on casspool.dat, mvsspl01.dat or catalog.dat.

These return codes indicate that the file i/o on the associated file has returned an unexpected status code. This can happen for a number of reasons. For example, because another process has the file locked, because an expected record no longer exists or an invalid catalog or archive location has been specified.

If the resulting return code indicates a serious error (16) or the errors are persistent, CTF tracing for the MVSP0027 housekeeping process is available (which will log the file status codes encountered for a precise diagnosis). The appropriate settings for CTF are:

mftrace.level.mf.mvs.mvsp0027  = debug
mftrace.comp.mf.mvs.mvsp0027#entry      = true
mftrace.comp.mf.mvs.mvsp0027#delete     = true
mftrace.comp.mf.mvs.mvsp0027#warning    = true

CTF tracing for the MVSSPLHK process is not required, because diagnostic information is written to the SYSPRINT file.

When CTF tracing is set or you are running the MVSSPLHK process, and a spool housekeeping operation fails, the return code is accompanied by a reason code. The reason code can help locate the source of the spool housekeeping problem, and can also help to diagnose errors.

Note: Reason codes 01 to 53 (except 06 and 07) are applicable to all housekeeping processes; reason codes 06, 07, and 60 onwards are applicable to the MVSSPLHK process only.
Reason code | Explanation
01, 02 | Read next record on casspool operation failed.
03 | Purge record on casspool operation failed.
04 | Delete record on casspool operation failed.
05 | Start on casspool operation failed.
06 | Casspool open error.
07 | Casspool read key error.
10 | Open on mvsspool operation failed.
11 | Delete record on mvsspool operation failed.
12 | Read next record on mvsspool operation failed.
13 | Keyed read on mvsspool operation failed.
20 | Open on profile (the .pro file describes the spool archive file for data file editor - only when archiving requested ) operation failed.
21 | Write on profile ( only when archiving requested ) operation failed.
30 | The Copy spool to archive operation failed. The spool archive directory may not exist.
40 | The Read record on catalog.dat file operation failed.
41 | The delete record from catalog.dat file operation failed.
42 | A get next record from catalog.dat file operation failed.
43 | A start not greater than on catalog.dat file operation failed.
44 | An undefined error occurred while performing a catalog file operation.
50 | A start not greater than on MVSOUTIO.dat failed while removing expired output dataset entries.
51 | A read next on MVSOUTIO.dat failed while removing expired output dataset entries.
52 | A delete on MVSOUTIO.dat failed while removing expired output dataset entries.
53 | An undefined error occurred while performing a file operation on MVSOUTIO.dat while removing expired output dataset entries.
60 | Archive catalog open error
61 | Archive catalog write error
63 | Other archive catalog error
64 | Archive casspool open error
65 | Archive casspool write error
66 | Other archive casspool error
67 | Archive mvsspool (spool file information) open error
68 | Archive mvsspool write error
69 | Other archive mvsspool error
70 | Configuration (either CONFIGI or SYSIN) open error
71 | Configuration read error
72 | Other configuration error
73 | INDEXO open error
74 | INDEXO write error
75 | Other INDEXO error
76 | Archive MVSOUTIO (OUTPUT statement information) open error
77 | Archive MVSOUTIO write error
78 | Other archive MVSOUTIO error
80 | Report file (SYSPRINT, SYSOUT, SYSERR) open error
81 | Report file (SYSPRINT, SYSOUT, SYSERR) write error
82 | Other report file (SYSPRINT, SYSOUT, SYSERR) error
83 | Report file close (SYSPRINT, SYSOUT, SYSERR) error
90 | Archive already exists - when doing a FULL archive then the archive directory (created under the MF_SPOOL_ARCHIVE_LOC) must not exist.
91 | Error parsing the configuration file (CONFIGI or SYSIN)
92 | Invalid configuration setting
99 | Other processing error
Parent topic: Spool Housekeeping
Related information
MVSP0027 Spool Housekeeping Process
MVSSPLHK Spool Housekeeping Process
Spool Housekeeping-specific Environment Variables


Running the Spool Housekeeping Program from JCL

The spool house keeping program, MVSP0027, can be called in batch from a user-written program run by JCL.

To do this, you must write your program to assign the fields as indicated by the instructions in copybook spoolhk.cpy, found in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib , and call MVSP0027. For example:

Example JCL to call your program

//EXAMP1 JOB 'CPTEST',CLASS=A,MSGCLASS=A
//STEP01 EXEC PGM=MFSPHK01
//SYSOUT DD SYSOUT=*
//OFILE  DD SYSOUT=*

Example program to invoke housekeeping

000100 IDENTIFICATION DIVISION.
000300 PROGRAM-ID. MFSPHK01.
003100***************************************************************
004600 ENVIRONMENT DIVISION.
004700 input-output section.
       file-control.
           select infile assign to ifile organization is sequential
                  file status is status-codei.
           select outfile assign to ofile organization is sequential
                  file status is status-codeo.
       DATA DIVISION.
       file section.
       fd  infile.
       01  inrec                         pic x(80).
       fd  outfile.
       01  outrec                        pic x(120).
       WORKING-STORAGE SECTION.
       01 status-codei                   pic xx.
       01 status-codeo                   pic xx.
       01 ws-message                     pic x(120).
       01  spool-hk-settings.
           copy spoolhk.cpy.
       01  ws-mvsp0027-rc                pic xx comp-5.
       01  ws-mvsp0027-reason            pic xx.
       01  disp-num                      pic 99.
       PROCEDURE DIVISION.

      *****************************************************************
      *                                                               *
      *****************************************************************
       0000-MAINLINE-MODULE.
           move 0 to ws-mvsp0027-rc
           call 'mvsp0027' using spool-hk-settings
                                ws-mvsp0027-rc
                                ws-mvsp0027-reason
           move spaces to ws-message
           evaluate ws-mvsp0027-rc
             when 0
               string
                    'SPOOL CLEAN-UP ENDED NORMALLY' delimited by size
                    ' maximum retain period is '    delimited by size
                     ws-keep-for                    delimited by size
                     ' days. '                      delimited by size
               into ws-message
             when 4
               string
                    'SPOOL CLEAN-UP ENDED, '        delimited by size
                    ' empty CASSPOOL/MVSSPOOL  '    delimited by size
                    ' maximum retain period is '    delimited by size
                     ws-keep-for                    delimited by size
                     ' days. '                      delimited by size
               into ws-message
           when other
               move  ws-mvsp0027-rc  to disp-num
               string
                    'SPOOL clean-up failed RC = '  delimited by size
                     disp-num                      delimited by size
                    ' reason code = '              delimited by size
                     ws-mvsp0027-reason            delimited by size
               into ws-message
           end-evaluate
           display ws-message upon console
           goback.

       FILE-INPUT SECTION.
           perform open-infile
           perform read-infile
           PERFORM UNTIL status-codei NOT = '00'
              *> populate mvsp0027 parms
              perform read-infile
           end-perform
           .

       open-infile section.
           open input infile
           if status-codei = '00'
               continue
           else
               move 12 to return-code
               goback
           end-if
           .
       read-infile section.
           read infile
           evaluate status-codei
               when '00'
               when '10'
                   continue
               when other
                   move 16 to return-code
                   goback
           end-evaluate
           .
Parent topic: Configuring Enterprise Servers for JCL


Controlling where Datasets are Created

To override the default location used during the creation of datasets, you can configure Enterprise Server to consult a file containing rules that determine where new datasets are created.

You do this by setting the ES_ALLOC_OVERRIDE environment variable to the location of the "rules" file. See Format of the Rules File for information about how to create rules in the rules file.

  • Format of the Rules File
  • Old Format of the Rules File
Parent topic: Configuring Enterprise Servers for JCL


Format of the Rules File

The rules file is a text file that can include multiple rules. You can set conditions on specific field names and define multiple conditions within a single rule.

A rule is defined using the following format:

RULE:
    - CONDITION:  condition
      VALUE:      value
    SUBDIRECTORY: location
---

Where:

  • RULE: defines the start of the definition of a rule and --- indicates where it ends.
  • -CONDITION: indicates where a condition starts.

    A rule can have multiple conditions.

  • A condition must be followed by a VALUE: that specifies the condition value.
  • SUBDIRECTORY indicates a dataset or a file location. Can be a full path or an environment variable.

    A rule can have only one SUBDIRECTORY: entry.

The following is example of a rule that sets a condition for the RECORDTYPE property with a value of 'S'. This indicates that any SPOOL file should be assigned to the $MFSYSCATDIR\SPOOL\ folder ($MFSYCATDIR is an environment variable that indicates the folder that stores the system catalog):

RULE:
    - CONDITION:	RECORDTYPE
      VALUE:		S
    SUBDIRECTORY:	$MFSYSCATDIR\SPOOL\
---

Names of the catalog record fields

The following names can be used in the rules to indicate catalog record fields:

RECORDTYPE
Type of the catalog record:
S
A spool record
D
A data class record
DSNAME1 - DSNAME5
Name of the dataset name element, number one to five: DSNAME1.DSNAME2.DSNAME3.DSNAME4.DSNAME5
DSORG
Dataset organisation. Can be one of the following:
  • PDSM
  • PO
  • PS
  • VSAM
  • GDG
  • IS
LRECL
The record length. Must have a numeric value.
RECFM
The record format. Can be one of the following:
  • F, FA, FB, FBA, FBM, FBS, FM (Fixed)
  • KS, ES, RR, LS (VSAM Files)
  • LSEQ (Line sequential)
  • U (Undefined)
  • V, VA, VB, VBA, VBM, VBS, VM, VS (Variable)
CHARSET
The character set. Takes the following values:
A
ASCII
E
EBCDIC
DATACLASS
The data class of the dataset.
MGMTCLASS
Management class value - The management class of the dataset
UNIT-DEVICE
The unit value of the dataset.
VOLUME
The volume value of the dataset.
JOB-CREATED
The name of the JCL job that created the dataset.

Defining multiple conditions with a rule

You can define multiple conditions within a single rule.

The following example shows a rule for a dataset that has a character set of ASCII; its dataset name has 'PROD' as its first element and 'I' as its fourth element (for example, PROD.BBBB.CCCC.I.EEEE); has a UNIT setting of 'SYSDA'; a RECFM setting of 'VB'; was created by the JCL job 'OVERCHK'; will be created in the '$MFSYSCATDIR\RECFM\' folder:

RULE:
    - CONDITION:	CHARSET
      VALUE:		A

    - CONDITION:    DSNAME1
      VALUE:        PROD

    - CONDITION:    DSNAME4
      VALUE:        I

    - CONDITION:    UNIT-DEVICE
      VALUE:        SYSDA

    - CONDITION:    RECFM
      VALUE:        VB

    - CONDITION:    JOB-CREATED
      VALUE:        OVERCHK

    SUBDIRECTORY:	$MFSYSCATDIR\RECFM\
---

Using HEX values

You can use hexadecimal values in the rules.

The following example shows a rule that is defined for the dataset LRECL field - if it has a value of H'0063' (decimal 99), it will be assigned to the LRECL99 folder:

RULE:
    - CONDITION:  LRECL
   VALUE:      HEXVALUE 0063
    SUBDIRECTORY: $MFSYSCATDIR\LRECL99\
---

Using wildcards

The rules file has a simple wildcard support. You can use a single or multiple wildcards, *, in the value field to indicate any number of characters - for example, L00*500 or *TE*.**S*.

The following example rule specifies that a dataset whose first name element is ‘PROD’ and whose management class begins with ‘L00’ and ends with ‘500’ is to be assigned to the L00D500 folder:

RULE:
    - CONDITION:	DSNAME1
      VALUE:	PROD

    - CONDITION:	MGMTCLASS
      VALUE:	L00*500

    SUBDIRECTORY:	$MFSYSCATDIR\L00D500\
---

Automatic selection of classes

The format of the rules file enables you to assign properties to a dataset based on the same conditions. This can be likened to the Automatic Class Selection process on the mainframe.

You can assign the following attributes to a dataset:

DATACLASS
The name of the DATACLASS
MGMTCLASS
The name of the MGMTCLASS
CHARSET
The character set to use:
A
ASCII
E
EBCDIC
EXPIRE
The expiry time
SUBDIRECTORY
The directory to use for the dataset location. This is the same directory, SUBDIRECTORY, that is used in the general definition of a rule.

The following example shows a rule that specifies that any dataset that has a first name element of ‘MFI01’ and a fourth name element of ‘F2’ is to be assigned to the $MFSYSCATDIR\MFI01\ENDINF2 folder and have the MANGEMENGTCLASS property set to ‘MGMTYYYY’ and the EXPIRY date set to 4 days hence (a specific value can also be used):

RULE:
    - CONDITION:	 DSNAME1
      VALUE:      MFI01

    - CONDITION:	 DSNAME4
      VALUE:      F2

    SUBDIRECTORY:	$MFSYSCATDIR\MFI01\ENDINF2

    - ATTRIBUTE:  MGMTCLASS
      VALUE:      MGMTYYYY

    - ATTRIBUTE:  EXPIRE
      VALUE:      +4

---

For more examples of the allocation rules, see the Mainframe Samples available with this product - Start > All Programs > Micro Focus Enterprise Developer > Samples > Mainframe Samples, and select the JCL – Allocation Override sample.

Parent topic: Controlling where Datasets are Created


Old Format of the Rules File

Releases of Enterprise Developer earlier than 2.3 used a different format of the rules file which is described further in this topic.

Note: Micro Focus recommends you use the newer rules file format when defining new override locations as this format provides more flexibility in specifying conditions and catalog record fields. The older file format is still supported for backward compatibility so there is no need to change any existing configuration files.

Each rule in the file specifies: an offset from the beginning of the catalog record, a value that will be found at the offset in records for datasets that match the rule, and a directory in which the files for those datasets will be created.

For example, the following rule:

OFFSET(n) VALUE (MYSTRING) SUBDIR (C:\MYDIR\MYSUBDIR)

will allocate to C:\MYDIR\MYSUBDIR all files that contain the string "MYSTRING" at position n of the catalog record. The catalog structure is defined in the copyfile: mvscatlg.cpy. This is located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib .

Each rule must occupy only 1 line and all keywords must be in uppercase. Rules are processed in the order that they appear in the file, and the first one that matches is the one that is used; that is, no further rules are consulted for that dataset.

Parent topic: Controlling where Datasets are Created


Separating the Spool Files From the Main Catalog File

By default, casspool.dat and the other spool control files are placed in the same folder as the catalog.dat file. You can take one of the approaches outlined below to enable the use of the spool files and the catalog from different locations:

  • Use the File Handling Redirector (FHRedir) module and an allocation override rule.
  • Specify the MVSSPOOLDIR environment variable.
  • Use multiple catalogs and allocation override rules.

Using FHRedir and an allocation override rule

You can use the File Handling Redirector (FHRedir) module in combination with an allocation override rule to send the casspool control files and the spool datasets to a different Fileshare server from the one where the main catalog is stored.

There are different locations in FHRedir for the catalog and the spool files:

/f C:\ES_ERRORS\FAST_CAT_FS\CATALOG.DAT /s CATSERVER
/f C:\ES_ERRORS\FAST_CAT_FS\SMS.DAT /s CATSERVER

/f C:\ES_ERRORS\FAST_CAT_FS\casspool.dat /s SPOOLSERVER
/f C:\ES_ERRORS\FAST_CAT_FS\MVSJOBDS.DAT /s SPOOLSERVER
/f C:\ES_ERRORS\FAST_CAT_FS\MVSOUT01.dat /s SPOOLSERVER
/f C:\ES_ERRORS\FAST_CAT_FS\MVSSPL02.DAT /s SPOOLSERVER

In order to send the spool files to the same Fileshare server as the spool control files and store all these files together, create and apply the following allocation override rule:

# RECORDTYPE = S

RULE:
    - CONDITION:	RECORDTYPE
      VALUE:		S
    SUBDIRECTORY:	$$SPOOLSERVER\SPOOL\
---

Using the MVSSPOOLDIR environment variable

You can use the MVSSPOOLDIR environment variable to specify the location of all spool control files. If you set this variable to a value that contains the name of a Fileshare server (for example, $$SPOOLSERVER), you do not need to specify the FHRedir settings mentioned in the previous approach because all control files would be directed to the Fileshare server.

Using multiple catalogs and allocation override rules

You can use multiple catalogs in combination with some allocation override rules to direct all spool files to a separate location which could be a Fileshare server. See Multiple Catalog Support for more details.

Example

The following example shows how to use environment variables to separate the spool files from the main catalog file:

MFSYSCAT=$$CATSERVER\CATALOG.DAT
 Specifies the main catalog.
MVSSPOOLDIR=$$SPOOLSERVER
 Directs the spool control files to the SPOOLSERVER.
MFALLOC_LOC=%CD%\DATA
 Specifies the main data file location.
MFUSERCAT_LOC=%CD%\SMS.DAT;$$SPOOLSERVER\CATALOG.DAT;%CD%\LOCAL_CATALOG\CATALOG.DAT
 Specifies the different catalog files to use.
MFUSERCAT_NODE=SYSMFE1;MVSSPOOL;MFITEST
 Specifies which datasets to use the catalogs for.
ES_ALLOC_OVERRIDE=%CD%\Allocation.cfg
 Specifies the allocation override rules that direct the files to different locations.
Parent topic: Configuring Enterprise Servers for JCL


Restarting Jobs

As long as the job has not been hard-killed, Enterprise Server provides support for restarting JCL jobs at a specified step and, optionally, a procstep. A job that has been hard-killed no longer possesses the job information required to be able to restart.

A typical sequence of events is as follows:

  • The job completes and remains on the Output Hold queue.
  • The user requeues the job for restart using either ESMAC, the casout command, or the callable API, specifying the step and (optionally) the procstep.
  • The job is put back into the Input queue.
  • The job is rescheduled and restarts at the specified step/procstep.
  • Enabling job restart functionality
  • Restarting a job
  • Non-restartable steps
  • Processing during restart
  • GDG Processing during Restart
Parent topic: Configuring Enterprise Servers for JCL
Related reference
casout


Enabling job restart functionality

The restart functionality is governed by two environment variables:

ES_JES_RESTART Setting this variable to Y has the following effects:
  • ESMAC will display new fields for a job's details on the Output Hold queue, along with a Restart button. The new fields allow you to specify the step and procstep at which the job is to restart.
  • When the job is run, the lexical files (MFELX*.DAT) associated with the job will no longer be cleaned up when the job is completed; instead, these files will be cleaned up when the job is deleted.
MF_UCC11
Note: This environment variable works independently of the JCL RESTART parameter.
Setting this environment variable to Y enables:
  • Automatic reset of the GDG bias to the level of the prior run of the job; that is, the restart will automatically pick up the "correct" GDG Bias.
  • Restarting a job with DISP=(NEW,CATLG) datasets will not result in job failure due to the dataset already being cataloged.
  • COND Code Processing and IF/THEN logic that is dependent upon COND codes from prior steps that are skipped by the RESTART will work as expected with no changes to the JCL.

When this environment variable is set to M, on a restart a catalogued a dataset is presumed to have an initial disposition of MOD rather than NEW. As a result, any new data is appended to the existing dataset.

Parent topic: Restarting Jobs


Restarting a job

As long as a job has not been hard-killed, you can restart the job through:

  • the ESMAC Job Details Page for a job on the "Output Hold" queue
  • the casout command line. For example:
    casout /r<Servername> /j<jobnumber:step:procstep>
  • driving the casout callable API
Parent topic: Restarting Jobs


Non-restartable steps

You cannot restart a job at a step if that step contains:

  • a //UCC11NR DD DUMMY statement
  • any temporary datasets that have DISP of SHR or OLD
Parent topic: Restarting Jobs


Processing during restart

On a restart:

  1. The joblog and all other SYSOUTs will be extended with new data unless they have already been printed/deleted.
  2. Any DISP=NEW datasets will cause an already existing dataset to be deleted before allocation.
  3. Any DISP=MOD datasets that already exist will be extended.
  4. Any DISP=OLD datasets will be over-written.

At the conclusion of the restarted job, its new execution state (step condition codes) will be saved for a future restart.

Note:
  • A non-unique restart step/procstep is resolved to its first occurrence and a message is issued upon restart. This is the same behavior as RESTART= on the JOB statement.
  • When a job is deleted from the Output Hold queue in ESMAC, from the casout command, or via the automated spool cleanup mechanism, all traces of the job are removed and it can no longer be restarted.
Parent topic: Restarting Jobs


GDG Processing during Restart

When a job that uses GDG bias is restarted, all references to a GDG relative bias (e.g. +1, -3) will cause the DD statement to reference the same physical file as the original job. The only time that this will not be true is where the processing of the original job (or of other jobs that were run after the original job) has caused the GDG Bias to be rolled off, scratched, or deleted.

In the case of most mainframe jobs there will be no issues but you should be aware of the following scenarios:

  1. Where a job runs to successful (non-abend) completion and this results in a GDG Bias being rolled off, that Bias will not be available on the restart and any step which references that bias will fail with a "dataset not found" message.
  2. Where a different job, which references the relevant GDGs and creates new relative biases, runs between the end of the job in question and before the job restart takes place, it is possible that the bias referenced by the restarted job will no longer be present.
  3. Where a job abends prior to completion, the abnormal termination disposition is applied as specified by the DISP= statements in the JCL. In this scenario you will encounter problems if the step at which you restart references a bias that doesn't exist as a result of the prior abnormal termination.
Parent topic: Restarting Jobs


Administering JCL-enabled Enterprise Servers

This chapter describes how you can use Enterprise Server Monitor and Control to run JCL jobs on an MSS-enabled enterprise server. It also covers the use of commands to use some JCL facilities.

  • ESMAC
  • On-the-fly SEPs for JCL
  • Running and Controlling JCL Jobs
  • Running JCL jobs held on the enterprise server machine
  • Managing and Viewing Spool Queues
  • Viewing the Catalog and Data Sets
  • Importing and Exporting a Catalog: import export utility
    Describes how to use the catalog import-export utility
  • Using JCL facilities from the command line
  • Interacting with JCL Jobs
  • Character Sets
Parent topic: JCL Support


ESMAC

You can use Enterprise Server Monitor and Control (ESMAC) to run and monitor JCL jobs. You can also use all the facilities described in the chapter Administering Servers Using ESMAC in your Enterprise Server Configuration and Administration Guide , and in the help topics grouped under Administer a Server Using ESMAC. You should familiarize yourself with the contents of that chapter and the associated help topics before reading this chapter.

As an alternative to using the ESMAC interface, you can use some JCL facilities from the command line. For more information see the section Using JCL Facilities from the Command Line.

  • Visual Appearance
Parent topic: Administering JCL-enabled Enterprise Servers
Related information
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 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
Administering Servers Using ESMAC
Using JCL Facilities from the Command Line


Visual Appearance

When you first view ESMAC for a JCL-enabled enterprise server, the Server Information page is displayed, as shown below:

Figure 1. ESMAC Server information page for JCL
ESMAC Server information page for JCL

When you run ESMAC on a JCL-enabled enterprise server, you can use it to:

  • Run on-the-fly SEPs for running JCL jobs and handling printer output
  • Submit and monitor JCL jobs
  • View the catalog
  • View spool queues
Parent topic: ESMAC


On-the-fly SEPs for JCL

As well as defining permanent batch initiators and printer SEPS, as described in the chapter Configuring JCL-enabled Enterprise Servers, you can run temporary ones that exist only until the end of the session.

Like all SEPs, the initiators and printers defined are shown, together with their statuses, on the SEPs page in ESMAC. Click SEPs near the top left of the ESMAC menu to display this.

  • To start a batch initiator or printer immediately
Parent topic: Administering JCL-enabled Enterprise Servers
Related information
To define a batch initiator or printer SEP
To start a batch initiator or printer immediately


Running and Controlling JCL Jobs

ESMAC provides facilities for running and controlling JCL jobs, using the JCL Control page.

When a job is submitted, it is immediately syntax checked, and then put onto an input queue to await execution. It goes into execution once an initiator of a corresponding class becomes available. If two or more jobs of the same class are on the input queue, the one with the highest priority is scheduled for execution first.

The default behavior, when using ESMAC to submit JCL job streams to an Enterprise Server, is for the file to be uploaded by the web browser and submitted across the wire (if the Enterprise Server is remote) along with other form data. In previous releases, you could use the ESMAC JES "Control" page (CASRDO44) to enter a file name that is only visible to the Enterprise Server instance.

Security changes implemented with Mozilla Firefox V3 and IE 8 prevent us from supporting this behavior. If you are using an older browser that still allows this behavior you can override it, and cause only the filename to be submitted to the Enterprise Server.

Once the job has completed, you can view details of its execution from the JCL Control page.

You see the JOBnnnnn page appears, where nnnnn is the number of the job. This page gives you access to several more facilities, described under the next section, Viewing Spool Queues .

You can view resource locks; you might want to do this if you suspect that a resource locking issue is holding up one of your JCL jobs.

  • To run a JCL job
  • To run a JCL job on a remote enterprise server
  • To view details of a job's execution
  • To view resource locks
  • Managing and Viewing Spool Queues
  • Handling "Out of Space" Errors
    What to do when you encounter an RTS error 9/007 in JCL.
Parent topic: Administering JCL-enabled Enterprise Servers
Related information
To run a JCL job
To run a JCL job on a remote enterprise server
To view details of a job's execution
To view resource locks
Viewing Spool Queues
Handling "Out of Space" Errors


Managing and Viewing Spool Queues

You can manage and view the spool queues from ESMAC.

The queues are listed below:

Button | Shows: | Details
Input | Input queue | Jobs waiting to start (usually waiting for an initiator for the correct class to be available)
In Hold | Held input queue | Jobs that are held (HOLD on the job card, or Hold button on a job’s entry in the Input Queue)
Active | Active jobs queue | Jobs currently running
Output | Output queue | Output files waiting to be printed (usually waiting for a printer for the correct class to be available)
Out Hold | Held output queue | Output files that are held (Hold button on a job’s entry in the Output Queue)
Printing | Print queue | Output files currently being printed

A spool queue that is not empty consists of entries for each job in the queue, with a button bearing the job number at the left-hand side of the page. You can click a job number button to view more details of the job. You see the JOBnnnnn page, where nnnnn is the number of the job. This page gives you access to several more facilities. You can:

  • Hold the job, that is, prevent the job from being executed if it is in the input queue or its output files from being printed if it is in the output queue
  • Update the control information for the job; this includes Class and Priority; you can use one or both of these to change the order in which jobs are run
  • Purge the job
  • View the details of any of the outputs from the job

The output file details page gives you access to some facilities for controlling and viewing individual output files. You can:

  • Hold the job, that is, prevent the job from being executed if it is in the input queue or its output files from being printed if it is in the output queue
  • Update the control information for the job; this includes Class and Priority; you can use one or both of these to change the order in which jobs are run
  • Purge the output file
  • View the contents of the output file
  • To view the spool queues
  • To delete a job
  • To delete a job output file
  • To delete all jobs in a queue
  • To hold or release a job
  • To update control information for a job
  • To view details of a job output file
  • To view details of a job's execution
  • To view the step condition codes for a job
  • To view the contents of a job output file
  • Active output jobs and server re-starts
    Describes the effect of running jobs when a region is re-started.
Parent topic: Running and Controlling JCL Jobs
Parent topic: Administering JCL-enabled Enterprise Servers
Related information
To view the spool queues
To view details of a job's execution
To hold or release a job
To update control information for a job
To delete a job
To view details of a job output file
To delete a job output file
To view the step condition codes for a job
To view the contents of a job output file
To delete all jobs in a queue


Handling "Out of Space" Errors

Unlike the mainframe, where constraints on file size are dictated by space allocation units (blocks, tracks, and cylinders), this JES system does not use the SPACE parameter when allocating files. Instead, it uses native file I/O methods, which behave differently. As such, your jobs may experience "out of space" errors, which are not the same as D37, E37, or B37 mainframe system abends.

What is an "out of space" error?

An "out of space" error is generated when data cannot be written to a file because there is no more space on the disk. When this error occurs, the file is in a corrupt state, since there is no way of knowing what data is missing from the file. This situation requires operator intervention to allow work to continue.

When these errors occur, they can have a severe impact upon a running system, as one error is likely to lead to many more, not only in files used by running batch jobs but also in those used by the system. For example, the system tries to report the error, which includes writing to a log file, whereupon that action experiences the same error. The whole system can, very quickly, become untenable and unable to continue.

How JES handles "out of space" errors

This JES system monitors the job exit code for an "out of space" error. If such a condition occurs, it frees the lock on the file, thereby permitting the end of step processing to take place, which may include removal of the file depending on the file's disposition. Subsequently, the system writes an error message to the console, and awaits operator intervention. Following the operator reply, the SEP is terminated at the end of that job, and a new SEP started.

This processing applies only to MVS files, that is those that have been defined with a DD statement in the JCL, or via SVC99. The suspension of job processing to await user input takes place only if the final job condition code is RTS error 9/007. The text of this message is displayed as "COND CODE RTS0007" in the job log. If the job ends with any other condition code, it is assumed that the job has included additional steps to process this error, or that a user exit has done so, and set the final condition code. See Using JCL User Exits for more information.

See below for sample messages, which also appear on the ES Console.

Display

An example of the spool messages for a job that produced an RTS 9/007 'out of space' error.

How to resolve "out of space" errors

You need to open the job spool view in a browser window, select the failed job on the list of Active jobs, and enter any character in the Reply field to continue processing. See To Reply to an ACCEPT FROM CONSOLE Statement for more information. To determine the file that caused the problem, click JESYSMSG under DD Name to view the system messages. You then need to carry out any remedial action necessary to correct the lack of disk space. This action might be one or more of the following:
  • Delete old files
  • Clean up temporary files
  • Archive files that have not been used for a long time
  • Move files to another disk
  • Extend the disk partition
Finally, you need to decide whether the failed job needs to be re-run.

Avoiding "out of space" errors

A well-managed system will include monitoring for free disk space to help ensure that "out of space" errors do not occur. There are other options the System Administrator can use to help reduce the impact of such errors. For example, you might wish to keep the system files on a different disk from those that are used in batch jobs. Alternatively, if certain jobs are known to produce large output files, then you need to keep those files on a different disk from other files.

Parent topic: Running and Controlling JCL Jobs


Running JCL jobs held on the enterprise server machine

When you are accessing an enterprise server session remotely, by default, ESMAC submits JCL jobs held on the machine running the web browser. If you are using a ESMAC and web browser to connect to a remote machine and you want to submit JCL that is only visible to the remote machine, then you will need to override the default behavior. (For example, if you are accessing an Enterprise Server session running on a Unix machine and configuring the session from a web browser running on a Windows machine, by default ESMAC runs JCL jobs held on the Windows machine.)

To access files from the machine running the Enterprise Server, configure the following environment variable:

CASRDO44_NEWSUB=OFF

See Environment Variables for details.

With this environment variable configured, from a remote machine, you can browse for and run JCL jobs located on the machine running the Enterprise Server session.

It is important to note that this behavior will only function if you are using a browser that allows an HTML element of TYPE=FILE to be used as an entry field for a filename, as opposed to the actual file being submitted as part of a MIME multi-part form.

(Firefox V3.0 and later and IE8 and later no longer allow this behavior.

Parent topic: Administering JCL-enabled Enterprise Servers


Active output jobs and server re-starts

If you boot an Enterprise Server region that shares a catalog with another Enterprise Server region that is currently running, the boot process flushes the restarted server's active jobs to the Held Output queue. As a result, these jobs disappear from each region's Active queue. The flush process only flushes jobs that have the same region name as the newly started region.

When a job is moved from Active to Output Hold as a result of a server restart, the Completion Code as viewed in the JES Output Hold queue is set to RFLS. This indicates that the job was flushed as a result of a restart.

To modify this behaviour, there is an environment variable that you can set to disable it.

If the environment variable ES_JES_DISABLE_RESTART_FLUSH is set to any value, then a region's jobs are not moved from the Active queue to the Output Hold queue when the region is re-started.

The recommended way to use this environment variable is to:

  • Set the ES_JES_DISABLE_RESTART_FLUSH environment variable for all online servers that share the Batch server's catalog.
  • Do not set the ES_JES_DISABLE_RESTART_FLUSH environment variable for all the Batch server.

This prevents the Online servers from purging the JES Active queue when they are cycled.

Parent topic: Managing and Viewing Spool Queues


Viewing the Catalog and Data Sets

You can view the catalog from ESMAC.

From the catalog page you can:

  • Create a catalog entry for a new data set
  • View the details of an existing catalog entry
  • Update an existing catalog entry
  • Delete a catalog entry
  • Copy a catalog entry to create a new entry
  • Import a system catalog from an XML file
  • Export the contents of an existing catalog to an XML file
  • View the contents of a cataloged data set
  • To view the catalog
  • To copy a catalog entry for a data set
  • To create a catalog entry for a data set
  • To delete a catalog entry for a data set
  • To update a catalog entry for a data set
  • Importing and Exporting a Catalog: import export utility
    Describes how to use the catalog import-export utility
  • To view the contents of a data set
  • To view the details of a catalog entry
Parent topic: Administering JCL-enabled Enterprise Servers


Using JCL facilities from the command line

You can use some JCL facilities from the command line. Commands are provided for:

  • Submitting JCL jobs
  • Starting batch initiator SEPs

These commands are described in detail in this chapter.

For any particular enterprise server, if you are going to invoke any functions via commands, you must use commands to start and stop that enterprise server. These commands are introduced in the section Command-line Interface in the chapter Servers in your Configuration and Administration Guide. All the commands are specified in detail in the help topics Commands.

  • Submitting JCL Jobs
  • Starting a Batch Initiator SEP
Parent topic: Administering JCL-enabled Enterprise Servers


Submitting JCL Jobs

You use the command cassub to submit a JCL job from the command line to an enterprise server running either on your own machine or a remote machine.

For a full definition of cassub see the topic cassub.

  • Submitting to a local machine
  • Submitting to a Remote Machine
Parent topic: Using JCL facilities from the command line


Submitting to a local machine

Before you use cassub to submit a JCL job on your machine, you must already have started the enterprise server using casstart.

If the enterprise server does not have a batch initiator SEP defined that handles jobs of the same class as the job you want to submit, you must also start a suitable batch initiator SEP using the command casout.

Example

casstart -rjcldemo
cassub -jC:\users\user-ID\documents\Micro Focus\Enterprise Developer\WORKAREA\jcldemo\esjcl\esjcl.jcl -rjcldemo

This submits the JCL in the file C:\users\user-ID\documents\Micro Focus\Enterprise Developer\WORKAREA\jcldemo\esjcl\esjcl.jcl to the enterprise server jcldemo.

Parent topic: Submitting JCL Jobs


Submitting to a Remote Machine

Before you use cassub to submit a JCL job to a remote machine, you must find out the address of the Web Services listener associated with the service MF JES. To do this:

  1. Open ES Admin for the remote machine.
  2. On the Home page of ES Admin click Details next to Services in the Objects column for the server that you want to submit a job to.
  3. Note the address of the listener for the service with a service class of MF JES.

You then specify this address using the -s parameter of cassub. For example:

cassub -jc:\users\username\Documents\Micro Focus\Enterprise Developer\WORKAREA\jcldemo\esjcl\esjcl.jcl -stcp:192.168.1.102:2811

If submitting to an ssl-enabled listener, -stcpssl can be specified in place of -stcp.

This submits the JCL in the file %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA on your machine to an enterprise server running on a remote machine. The enterprise server must already have been started.

You can verify that you have successfully submitted the job by using the ESMAC Log feature: click Log in the Diagnostics group of the menu, and then click Display. You will be able to see messages relating to the job submission.

You can view the remote machine's spool queues and catalog entries in the usual way.

  • To View and Use Remote Directory Server Instances
Parent topic: Submitting JCL Jobs
Related information
To view and use remote Directory Server instances


Starting a Batch Initiator SEP

You use the command casout to start a batch initiator or batch printer SEP from the command line. Before you use casout, you must already have started the enterprise server using the command casstart.

Examples

casstart -rJCLDEMO
start casout -bABC -rJCLDEMO

This starts a batch initiator SEP for the classes A, B and C on the enterprise server JCLDEMO.

casstart -rJCLDEMO
start casout -bA -n"HP LaserJet 4L" -rJCLDEMO

This starts a batch printer SEP for the class A on the enterprise server JCLDEMO using the printer defined on your machine as "HP LaserJet 4L".

casstart -rJCLDEMO
start casout -bA -n"HP LaserJet 4L" -rJCLDEMO -xSAMPPRNX

This is as above, with the differences that the printer exit SAMPPRNX is installed.

Note that it’s advisable to run the command casout in a separate session, using the Windows start command as shown.

Parent topic: Using JCL facilities from the command line


Interacting with JCL Jobs

You can run jobs on an enterprise server that 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 job log, and the job continues. When execution reaches an ACCEPT FROM CONSOLE statement, the job pauses and asks for input using pages in ESMAC.

There is also a facility for replying to ACCEPT FROM CONSOLE statements in basic ESMAC for running Web services, and this is available to JCL jobs. For more information see the sectiion Interacting with Services in the chapter Administering Servers Using ESMAC in your Configuration and Administration Guide.

  • To reply to an ACCEPT FROM CONSOLE statement
Parent topic: Administering JCL-enabled Enterprise Servers
Related information
To reply to an ACCEPT FROM CONSOLE statement


Character Sets

Migrated JCL applications used to run on the mainframe using the EBCDIC character set. However, the native character set on Windows and UNIX machines is ASCII. On Enterprise Server you can continue to run JCL applications in EBCDIC if you wish, or you can run them in ASCII. There are both program and data considerations.

  • Programs
  • Data
Parent topic: Administering JCL-enabled Enterprise Servers


Programs

The default mode for an enterprise server is ASCII, since Windows, like UNIX, is an ASCII environment. Programs can be run in EBCDIC as long as they have been compiled using directive CHARSET"EBCDIC". At the beginning of a program execution, that is, the execution of a program invoked by the CALL command, the RUN sub-command (of DSN), or by a job step (PGM=), the JCL engine detects the character set of the program. The character set of the program remains constant throughout its execution.

Steps in a JCL job stream can use different character sets. But if a program initiated by a job step then calls another program, it's up to the programmer to make sure that the character sets used by the programs are compatible (for example for call parameters) or that they handle any incompatibilities themselves.

Parent topic: Character Sets


Data

The programmer needs to ensure that any data files they read are in the character set that matches the program. The File Handler will issue an abend if it is asked to open a file whose catalog entry has a different character set from the character set of the program.

In-stream data and line sequential files are automatically converted to match the mode of the application program. Data in all other files is not converted.

All data presented to or exchanged with the program is either ASCII or EBCDIC depending on the character set of the program. Conversions are done as appropriate. This includes data in MVS control blocks.

Pointer data is native unless AMODE is in effect, in which case, it is big-endian (network order). This includes data in MVS control blocks.

Binary data is always big-endian. This includes data in MVS control blocks.

Parent topic: Character Sets


z/OS Enterprise Server Extensions

Enterprise Server provides extensions to several MVS features. These extensions can be added to existing source and can remain there since they are treated as comments by the host operating system.

You write the extensions as comments, so that if you move your JCL or IDCAMS back to the mainframe they are ignored. The start of the Micro Focus extensions within a comment is indicated by the four-character string “MFE:”. Extensions are identified by keywords. These keywords begin with the % sign, to avoid any possible conflict with z/OS keywords.

There is no change to standard JCL or IDCAMS comments.

  • JCL Extensions
    Describes JCL extensions as used with Enterprise Server.
  • IDCAMS Extensions
    Describes the extensions Enterprise Server provides to the IDCAMS command language.
  • %REPRO Extension
    Describes %REPRO extension behavior.
  • %PCDSN Extension
    Specifies a physical PC filename to be associated with the MVS data set name.
Parent topic: JCL Support


JCL Extensions

Describes JCL extensions as used with Enterprise Server.

Syntax:

//*MFE: {keyword=value}[...]

Syntax Rules:

  1. //*MFE: must be coded in columns 1 through 7
  2. Keywords must start in column 8 or after
  3. All extension keywords begin with the % sign

General Rules:

  1. Code each extension on a line following the last line of the entire JCL statement to which it applies.
  2. All other JCL syntax rules apply.

Parameters:

keyword=value Specify an extension keyword and value. All extension keywords must begin with the % (percent) character.

Example:

//STEP1    EXEC PGM=MYPROG,REGION=1024K,
//              ACCT=(‘ACCOUNT INFO’),
//              PARM=’parameter string’
//*MFE:         %TYPEXEC=HOST,%SOMEOTHER=SOMEVAL
//*MFE:         %ANOTHER=VAL

In this example, three extension keywords apply to the EXEC statement and follow the complete statement. %TYPEXEC, %SOMEOTHR, and %ANOTHER are extension keywords.

  • JOB Statement Extensions
    Lists each JOB statement extension and provides a description of each.
  • DD Statement Extensions
    Lists each DD statement extension and provides a description of each.
Parent topic: z/OS Enterprise Server Extensions


JOB Statement Extensions

JOB Statement Extensions
%CATMAINT({Y | N | D} [,partial-dsname]) | Specify whether a catalog maintenance step is automatically generated at job end. It can be used with or without RJSE, and is RJSE independent.
 | Y | Generate a maintenance step at job end. If specified without partial-dsname, the entire catalog is read.
 | N | Do not generate a maintenance step at job end (default)
 | D | Generate a maintenance step at job end, and delete the audit log SYSOUT dataset (becomes DD DUMMY). If specified without partial-dsname, the entire catalog is read.
 | partial-dsname | Specify a partial dataset name. Valid only in combination with Y or D. The catalog maintenance utility looks only at catalog records for datasets that begin with the specified partial-dsname value, thus limiting the search. Each selected record is presented to the user exit (mfcatmntue) as before. In addition to current functions, the exit might, at initialization time, change the partial dataset name and/or the expiry date.
%HLQ =value | RJSE only. Specifies a dataset name High Level Qualifier (HLQ) used for generated dataset names instead of the user ID.
 | value | A high level qualifier up to 8 characters in length. It is not validated for syntax, but should be valid as a z/OS dataset name HLQ.
%MFA ={RJSE | ALL} | Change the setting of the environment variable MF_MFA for the life of this job only.
 | RJSE | Search for datasets in the local catalog only. No mainframe is performed.
 | ALL | Search for datasets first in the local catalog, and if not found, on the mainframe.
 | Note: This keyword is ignored if the environment variable MFASERV is not ON.

Examples:

%CATMAINT Example

%CATMAINT=(Y,MFIDSA.D)
%CATMAINT=D
%CATMAINT=(Y,MFI01.DSA)
//MFIDSAR9 JOB (MFIDSART),CLASS=A,
//             MSGCLASS=X,MSGLEVEL=(1,1),USER=MFIDSA,
//             REGION=0M
//*MFE:%CATMAINT=(Y,MFI01.DSA)

%HLQ Example

%HLQ=MFI01.DA
%HLQ=MFIDSA
%HLQ=PQ.R.S.T
//MFIDSAR9 JOB (MFIDSART),CLASS=A,
//             MSGCLASS=X,MSGLEVEL=(1,1),USER=MFIDSA,
//             REGION=0M
//*MFE:%HLQ=MFI01.DA

%MFA Example

%MFA=RJSE
Parent topic: JCL Extensions
Related reference
JCL-specific environment variables


DD Statement Extensions

Lists each DD statement extension and provides a description of each.
DD Statement Extensions
%PCDSN=pcdatasetname When creating a new dataset, specify a data file on the local PC for a new dataset that you want to associate with the z/OS dataset name.
  • If you omit this parameter, Enterprise Server generates a PC filename automatically.
  • This parameter is valid only with new data sets (i.e., DISP=NEW and DISP=MOD that is new), and is ignored for old data sets (i.e., DISP=OLD, DISP=SHR, DSIP=MOD that is old).
  • If necessary, enclose pcdatasetname in single quotes.
  • If the filename specified for pcdatasetnamecontains spaces, enclose the name in double quotes (").
  • The specified filename cannot exceed 256 characters, including all characters between single quotes and including double quotes that enclose the PC filename.
%UPLOAD={YES | NO | AUTO} | RJSE only.
YES | Upload the dataset referenced by the DD
NO | Do not upload the dataset referenced by the DD
AUTO | Have the system make the determination whether or not to upload the dataset (default)
%DOWNLOAD={YES | NO | AUTO} | RJSE only.
YES | Download the dataset referenced by the DD
NO | Do not download the dataset referenced by the DD
AUTO | Have the system make the determination whether or not to download the dataset (default)
%PDSMEM={ALL | ONLY} | RJSE only.
ALL | Upload or download the entire PDS referenced by the DD
ONLY | Upload or download only the PDS member referenced by the DD
Note: This option is ignored if the dataset is not a PDS.
%CHARSET={EBCDIC | ASCII} RJSE only. Specify the character set for a new dataset. By default, the character set is the same as the character set of the system.
Note: This parameter is for Micro Focus internal use only unless justified otherwise.
%LSEQRECF={V | VB | F | FB} | Specify the appropriate host record format for the uploaded RECFM=LSEQ dataset.
V | Upload as RECFM=V dataset
VB | Upload as RECFM=VB dataset
F | Upload as RECFM=F dataset
FB | Upload as RECFM=FB dataset (default)
Note: We strongly advise that you set LRECL for local LSEQ datasets to a valid value other than 0. When the LRECL value is 0, the system assumes a host dataset LRECL of 80 for F and FB, or 255 for V and VB, and issues a warning message. This could lead to other failures.
%RELATED={[YES | NO | AUTO)} | RJSE only. Specifies whether to move the dataset from one location to another. This must be specified on the DD statement if the same dataset exists on the host as well as the PC. The two datasets with the same name are presumed to be not related to each other and may contain different contents. The host dataset is used only by jobs running on the host and the PC dataset is used only by jobs running locally.
YES | Move the dataset from one location to another
NO | Never move the dataset from one location to another (default)
AUTO | Have the system make the determination whether or not to move the dataset
Important: Causes all other RJSE-related DD parameters to be ignored.

Examples:

%PCDSN Example 1

//NONVSAM  DD DSN=MFIDSA.RJSE.NONVSAM.WITH.SPECIFIC.PCNAME,
//            DISP=(NEW,CATLG),SPACE=(TRK,1),LRECL=80,
//            RECFM=F,DSORG=PS
//*MFE:       %PCDSN='"F:\MX30 JCL SYSTEM\PCFILE.NONVSAM.DAT"'

The specified filename contains spaces and therefore requires double quotes.

%PCDSN Example 2

Assign a PC physical filename to a data set you are creating using JCL:

//SYSUT2   DD DSN=MFIDSA.NONVSAM.WITH.SPECIFIC.PCNAME,
//            DISP=(NEW,CATLG),SPACE=(TRK,1)
//*MFE:       %PCDSN='<CATALOGFOLDER>\MYFILE.NONVSAM.DAT'
  • The string <CATALOGFOLDER>, written exactly as shown, means the folder containing the catalog.
  • The single quotes surrounding the value are required here because the value contains lower-case characters and greater-than and less-than signs (<>) and therefore does not conform to JCL syntax rules.

%PCDSN Example 3

Create a dynamic PDS:

//DD1      DD DSN='TEST.DYN1',DISP=(NEW,CATLG),
//            DCB=(RECFM=FB,LRECL=123,DSORG=PO)
//*MFE:       %PCDSN=C:\DPDS\*.DAT

This creates TEST.DYN1 as a dynamic PDS whose members are files in the directory C:\DPDS with the extension .DAT. The data set organization must be PO.

%UPLOAD, %PDSMEM Example

//STEP1    EXEC PGM=MYPROG,REGION=1024K,
//              ACCT=(‘ACCOUNT INFO’),
//              PARM=’parameter string’
//*MFE:         %UPLOAD=YES,%PDSMEM=ALL

%CHARSET Example

//SYSUT2   DD DSN=MFIDSA.NONVSAM.EBCDIC.DATASET,
//            DISP=(NEW,CATLG),SPACE=(TRK,1)
//*MFE:       %CHARSET=EBCDIC

%TYPEXEC Example

//HOST1    EXEC OGN=HOSTPGM, REGION=1024K,
//              PARM='parameter string'
//*MFE:         %TYPEXEC=HOST

This indicates that this step is to be executed on the host system.

%RELATED Example

//DEF  DD DSN=MFIDSA.RC.SEQ,DISP=SHR
//*MFE: %RELATED=NO
Parent topic: JCL Extensions


IDCAMS Extensions

Describes the extensions Enterprise Server provides to the IDCAMS command language.

Syntax:

;MFE: {keyword(value)[,...]

General Rules:

  1. Code each extension on a line by itself following the last semicolon (;) that terminates the command to which it applies. If the command does not end with a semicolon, then add a semicolon.
  2. The value of the extension keyword follows normal IDCAMS rules for use of quotes, special characters, continuations, etc.

Parameters:

keyword(value) Specify an extension keyword and value. All extension keywords must begin with the % (percent) character.

Example:

DEFINE CLUSTER(NAME(MFIDSA.RJSE.VSAMKSDS.WITH.SPECIFIC.PCNAME ) -
        TRK(1 1) -
        ;MFE:%PCDSN -
         ('"F:\MX30 JCL SYSTEM\PCFILE.VSAMKSDS.DAT"')
  • DEFINE Statement Extensions
    Lists each DEFINE statement extension and provides a description of each.
Parent topic: z/OS Enterprise Server Extensions


DEFINE Statement Extensions

Lists each DEFINE statement extension and provides a description of each.
DEFINE Command Extensions
%PCDSN(pcdatasetname) Specify a data file on the local PC for a new dataset that you want to associate with the z/OS dataset referenced in the DEFINE command.
Note:
  • If you omit this parameter, Enterprise Server generates a PC filename automatically.
  • This parameter is valid only with new datasets and is ignored for old datasets.
  • If z/OS rules dictate, enclose pcdatasetname in single quotes.
  • If the filename specified for pcdatasetnamecontains spaces, enclose the name in double quotes (").
  • The specified filename cannot exceed 256 characters, including all characters between single quotes and including double quotes that enclose the PC filename.
%CHARSET({EBCDIC | ASCII}) Specify the character set for a new dataset. By default, the character set is the same as the character set of the system.
Note: This parameter is for Micro Focus internal use only unless justified otherwise.
CURRENT(n)

Specify the current generation when defining a generation data group for which the underlying G0000V00 datasets already exist. By default, the G0000V00 dataset with the highest G0000V00 number becomes the current generation, but this option allows you to make the G0000V00 dataset of your choice the current generation.

For example, if you currently have the datasets TEST.GDG.G9999V00, and TEST.GDG.G0001V00 allocated and then define a GDG called TEST.GDG, the two G0000V00 datasets become part of the TEST.GDG generation data group (GDG), and under normal behavior, the highest number would become the current generation; however, in this example the GDG has clearly cycled past the G9999V00, and using the CURRENT(1) extension allows you to make G0001V00 the current generation.

Example:

%PCDSN Example

DEFINE CLUSTER(NAME(MFIDSA.RJSE.VSAMKSDS.WITH.SPECIFIC.PCNAME ) -
        TRK(1 1) -
        RECSZ(80 80) KEYS(15 3)) -
        ;MFE:%PCDSN -
         ('"F:\MX30 JCL SYSTEM\ \PCFILE.VSAMKSDS.DAT"')

%PCDSN Example

DEFINE CLUSTER(NAME(MFIDSA.RJSE.VSAMKSDS.WITH.SPECIFIC.PCNAME ) -
        TRK(1 1) -
        ;MFE:%PCDSN -
         ('"F:\MX30 JCL SYSTEM\PCFILE.VSAMKSDS.DAT"')

CURRENT(n) Example

DEFINE GENERATIONDATAGROUP -
      (NAME(TEST.GDG) EMPTY SCRATCH LIMIT(5) CURRENT(1))
Parent topic: IDCAMS Extensions


%REPRO Extension

The %REPRO extension can be specified on the PARM keyword of the EXEC statement invoking IDCAMS, and on the PARM command. The syntax is:

%REPRO(VSAM | VSAMLAX | OSCOPY | OSCOPYLAX)
  • %REPRO(VSAM) provides the normal REPRO host compatible behaviour and is the default. In this case, for example, out of sequence records, when REPROing to a KSDS, will be flagged as an error.
  • %REPRO(VSAMLAX) provides the Micro Focus relaxed REPRO behavior. In this case, for example, out of sequence records, when REPROing to a KSDS, will be indicated with an information message.
  • %REPRO(OSCOPY) attempts to use the operating system's "file copy" facility to copy the underlying PC files. %REPRO(OSCOPY) is faster than %REPRO(VSAM), and is performed only if the data set attributes of the input data set match those of the output data set as indicated in the table below. An informational message is always issued indicating that the operation that took place.
  • %REPRO(OSCOPYLAX) is the same as %REPRO(OSCOPY), except that it still uses the operating system's "file copy" facility to copy the underlying PC files even if a subset of attributes do not match. The table below indicates which attributes must match for each command option. If the attributes at the bottom of the table (CHARSET, EXTENDED-TYPE, REUSE/NOREUSE, UNIQUEKEY/NONUNIQUEKEY) do not match, a message is issued but the system still proceeds with the operating system's "file copy".
Attribute | Must match for
RECFM | OSCOPY and OSCOPYLAX
DSORG | OSCOPY and OSCOPYLAX
VSAM-KEY-OFFSET | OSCOPY and OSCOPYLAX
VSAM-KEY-LENGTH | OSCOPY and OSCOPYLAX
LRECL | OSCOPY and OSCOPYLAX
LRECL-MAX (system managed) | OSCOPY and OSCOPYLAX
LRECL-MIN (system managed) | OSCOPY and OSCOPYLAX
CHARSET (EBCDIC or ASCII) | OSCOPY
EXTENDED-TYPE (system managed. Indicates base cluster, aix, etc.) | OSCOPY
REUSE/NOREUSE | OSCOPY
UNIQUEKEY/NONUNIQUEKEY (for AIXs and PATHs) | OSCOPY

For example:

//STEPAMS  EXEC PGM=IDCAMS,PARM=';MFE:%REPRO(OSCOPY)'
//SYSPRINT  DD SYSOUT=*
//VSAMDATA  DD *
AA
BBB
//SYSIN  DD *
  PARM ;MFE: %REPRO(VSAM)
  /* Next REPRO will use normal REPRO */
  REPRO  IFILE (VSAMDATA)                          -
         ODS   (MFIDSA.REPROOS.KSDS1)
  PARM ;MFE: %REPRO(OSCOPY)
  /* All REPRO(s), until another PARM command specifies –
     otherwise, will use OS copy if possible */
  REPRO  IDS   (MFIDSA.REPROOS.KSDS1)              -
         ODS   (MFIDSA.REPROOS.KSDS2)

The extension comes after a semicolon, so that the mainframe will see it as a comment. However, if the extension is the only option to the PARM command, the mainframe reports an error. To prevent this, you must code at least one option in addition to the extension. For example, rather than coding exactly as in the example above, you could code:

PARM='MAR(2,72);MFE: %REPRO(OSCOPY)'

or equivalently:

PARM   MAR(2,72);MFE: %REPRO(OSCOPY)
Parent topic: z/OS Enterprise Server Extensions


%PCDSN Extension

The %PCDSN extension can be used both in JCL and in IDCAMS. You use it when creating a new data set. It specifies a physical PC filename to be associated with the MVS data set name. If you do not use it, a PC filename is generated automatically.

For example, to assign a PC physical filename to a data set you are creating using JCL:

//SYSUT2 DD DSN=MFIDSA.NONVSAM.WITH.SPECIFIC.PCNAME,
//    DISP=(NEW,CATLG),SPACE=(TRK,1)
//*MFE: %PCDSN='<CATALOGFOLDER>\MYFILE.NONVSAM.DAT'

The extension comes after a "//*", so that the mainframe will see it as a comment. It must be on a line by itself and must follow the last of the DD statement lines to which it applies. The string "<CATALOGFOLDER>", written exactly as shown, means the folder containing the catalog. The quotes (note: single quotes) surrounding the value are needed if the name does not conform to JCL's rules; for example, if it contains spaces or lower-case characters.

Note: You can create dynamic PDSs by using this extension syntax as illustrated in the following example:
//DD1      DD DSN='TEST.DYN1',DISP=(NEW,CATLG),
//            DCB=(RECFM=FB,LRECL=123,DSORG=PO)
//*MFE: %PCDSN=C:\DPDS\*.DAT

This will create TEST.DYN1 as a dynamic PDS whose members are files in the directory C:\DPDS with the extension .DAT. The data set organization must be PO.

Similarly, to assign a physical PC filename to a data set you are creating using IDCAMS:

DEFINE CLUSTER( -
NAME(DSA.LIB.VSAMSRC2 )        -
CONTROLINTERVALSIZE (4096) -
RECORDSIZE(4088 4088) -
REUSE -
NUMBERED -
SHAREOPTION (4 4) -
CYLINDERS (2 1) -
) -
;MFE:%PCDSN(E:\MYDIR\MYFILE.DAT)

The extension comes after a semicolon, so that the mainframe will see it as a comment. We recommend that it be on a line by itself. Just as in JCL, you can use "<CATALOGFOLDER>" to mean the folder containing the catalog; and single quotes are needed surrounding the value if the name does not conform to IDCAMS's rules.

To continue the %PCDSN parameter over more than one line, you must following the JCL rules for continuations.

//SYSUT2 DD DSN=MFIDSA.TEST.NONVSAM.WITH.LONG.PCNAME,
// DISP=(NEW,CATLG),SPACE=(TRK,1),LRECL=80,RECFM=F,DSORG=PS
//*MFE: %PCDSN='<CatalogFolder>/DATA/pcname_long_name.node_name3.node_n
//*MFE:        ame4.node_name5.node_name6.node_name7.node_name8.node_na
//*MFE:        me9.with.long.pcname.for.nonvsam.dataset'

In this case, the name begins immediately after "=", goes on until column 71 (there is nothing in column 72), then resumes on the next line at column 16 and so on, finishing with the ending quote. Make sure you have //*MFE: in columns 1 through 7 of all records.

If the name ends exactly in column 71, the only thing left to put in the next line in column 16 is the ending quote:

//SYSUT2 DD DSN=MFIDSA.TEST.NONVSAM.WITH.LONG.PCNAME,
// DISP=(NEW,CATLG),SPACE=(TRK,1),LRECL=80,RECFM=F,DSORG=PS
//*MFE: %PCDSN='<CATALOGFOLDER>/DATA/PCNAME_LONG_NAME.NODE_NAME3.FL.DAT
//*MFE:        '

Finally, if you are using this in IDCAMS, then you follow IDCAMS rules (+ at the end etc. but columns 17/71 do not matter). For example:

DEFINE CLUSTER(NAME(MFIDSA.TEST.VSAMKSDS.WITH.LONG.PCNAME ) -
TRK(1 1) -
RECSZ(80 80) KEYS(9 0) ) -
;MFE:%PCDSN -
('<CatalogFolder>/DATA/pcname_long_name.node_name3.node_t+
ame4.node_name5.node_name6.node_name7.node_name8.node_nam+
e9.with.long.pcname.for.vsamksds.dataset')
Parent topic: z/OS Enterprise Server Extensions


Configuring JCL Timeouts

This chapter describes how you can configure timeouts for JCL jobs.

  • Overview: JCL Timeouts
  • Difference with the TIME= parameter
  • How the timeout is calculated
  • Establishing "Default" and "By Class" timeout values
  • New Messages
  • CTF Tracing/CAS AUX Tracing
Parent topic: JCL Support


Overview: JCL Timeouts

On a Z/OS system, both runaway and looping batch jobs can be controlled by the use of the TIME= parameter. This can operate on the JOB card. The TIME= parameter takes the form of: TIME=(x,y) where x is a time value in CPU minutes, and y is a time value in CPU seconds.

The Enterprise Server environment does not recognize the concept of CPU seconds. To allow for this, Enterprise Server includes a mechanism that enables you to configure a value in real seconds to equate to the CPU seconds that are coded in your JCL. Using this mechanism, you can configure a JCL job to abend long running jobs if they take longer than the boundaries you set.

A timeout can only be applied to a job when you have defined a class-specific timeout multiplier and/or a Default multiplier. If no class-specific or Default multiplier has been defined, a multiplier of 1 (one) is used. If multiple initiators are active, and a job is started, and then held awaiting the completion of another job of the same name, the time spent waiting is included in the job's elapsed time, when determining if the job has exceeded it's allotted time span.

Parent topic: Configuring JCL Timeouts


Difference with the TIME= parameter

The following topics illustrate the differences between JCL timeouts and using the TIME= parameter.

  • Abends - S322:
  • Maximum number of actual Seconds
  • Rerun/Recovery method
Parent topic: Configuring JCL Timeouts


Abends - S322:

On a mainframe, a job abends with an S322 abend code when the TIME value has been exceeded on a per job or per step basis.

The method used to end a job is as follows, depending on the platform on which Enterprise Developer is operating:

  • on a Unix environment, all terminations due to timeout are of the "hard kill" variety.
  • on the Win32 platform, the process first attempts a "soft kill." If this is unsuccessful it is immediately followed by a "hard kill".

    on Enterprise Server running on a PC, it is possible that your code is executing in a loop that is so tight that the timing mechanism is unable to break execution to terminate the job gracefully. In this event, it performs a "hard kill" on the process.

For all timeouts, the ESMAC Condition Code associated with the job is an S322. The job termination codes, as shown in the joblog, are either S222 in the event of a successful "soft kill" or nothing in the event of a successful "hard kill" In both cases a message similar to the one below is written to the console.log file:

CASKC6002I JOB10347 terminated due to exceeding TIME parameter 05:01:20

Parent topic: Difference with the TIME= parameter


Maximum number of actual Seconds

The maximum number of "real" seconds that can be used for a timeout value (calculated) for a JOB/STEP is 65533, or approximately 18.2 hours. If the time as calculated exceeds 65533 seconds, then a JES000034E message, as shown below, is issued to the console and the maximum value of 65533 seconds is applied to the job.

JES000034E JOB10348 - TIME parameter exceeds 65533 after applying class multiplier (0100)

Parent topic: Difference with the TIME= parameter


Rerun/Recovery method

On a mainframe, the third dataset disposition (abnormal termination) is always triggered and processed upon receipt of an S322 abend.

In the Enterprise Server environment however , the abnormal dataset disposition processing for an S322 abend is ONLY processed on the Windows Platform and only when a "soft kill" can be issued. If a "hard kill" is required to stop the job, for example on a UNIX platform, then you must treat the dataset dispositions for failing jobstep as "unknown," and reset the datasets accordingly. The DBMS commit/rollback can be used, and will process as expected

You can check the method: soft kill, or hard kill by examining the joblog for the failing job:

  • A joblog entry of S222 (operator cancel) indicates a soft kill, using abnormal dataset disposition processing.
  • If there is no job termination message entries, then the job was terminated with a hard kill.
Parent topic: Difference with the TIME= parameter


How the timeout is calculated

The timeout calculation is made by first attempting to apply a job CLASS-specific multiplier. If this multiplier is not present, the process applies the default setting. If neither is present, then a timeout multiplier of 1 (one) is applied to the job. In the example jobstream below, the job has specified a maximum TIME of 20 seconds of CPU time.

If CLASS=C jobs run with a multiplier of 2, then the job will run for between 40 and 50 seconds before being cancelled automatically by the system. This run time refers to actual execution time only, and does not include the time that the job spends in the INPUT or INPUT HOLD queues.

The Overhead value is a machine-dependant figure that is typically between 6 and 10 real seconds. It can vary in either direction depending upon the machine's workload and CPU speed. Any minutes specified on the JOB card are converted to CPU seconds before calculating.

The timeout is is calculated as follows:

Real Seconds = (TIME * Multiplier) + Overhead

For example, in the code below, the timeout is set for around 40 seconds.

//DMFBR14 JOB 'DMFBR14',CLASS=C,MSGCLASS=A,TIME=(,20)
//**************************************************************
//* Timeout after running for about 40 seconds. (Class C Multipler of 2)
//**************************************************************
//* Copyright (C) 1985-2008 Micro Focus International Ltd.
//* All rights reserved.
//**************************************************************
//*
//* Run one step for about 1 minute
//*
//STEP1 EXEC PGM=INFINITE,PARM='00012'
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//JBSTATUS DD SYSOUT=*,DCB=(LRECL=80,RECFM=FB,DSORG=PS)
//*
Parent topic: Configuring JCL Timeouts
Related information
To define a batch initiator or printer SEP
To start a batch initiator or printer immediately


Establishing "Default" and "By Class" timeout values

The sample jobstream below can be used to display and/or modify the settings used to calculate the number of actual seconds that can elapse before a job is cancelled automatically. In the code below:

  • The first step, LIST01, lists the current settings. These are written to the SYSPRINT DD and viewable via ESMAC in the Output Hold queue entry for the job.
  • .The second step, STEP10, establishes multipliers for classes A, B, C, and D, and sets a default setting of 10. The multiplier values must be 4 digits and can have a range of 0001 to 9999.
//SETMULT JOB 'SETMULT',CLASS=A,MSGCLASS=X,NOTIFY=MFIDMF
//*
//* List out all the values contained in jesinfo.dat
//*
//LIST01 EXEC PGM=MVSP0036,PARM='LIST'
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*,HOLD=Y
//SYSIN DD *
/*
//*
//* Set the values in jesinfo.dat for TIME= multipliers
//* as a default and on a class by class basis.
//* The multipliers are used in an attempt to equate CPU Seconds
//* to "real" seconds.
//*
//STEP10 EXEC PGM=MVSP0036,PARM='JESMULTIPLIER'
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*,HOLD=Y
//SYSIN DD *
DEFAULT(0010)
A(0009)
B(0004)
C(0002)
D(0100)
/*

Note the following:

  • The JESINFO.DAT file should not be manually edited. Its contents should only be updated via the MVSP0036 utility.
  • The JESINFO.DAT is in the same location as your catalog file, typically catalog.dat.
  • The settings in JESINFO.DAT are specific to an Enterprise Server region. These settings should not be shared among multiple servers.
Parent topic: Configuring JCL Timeouts
Related information
To view resource locks


New Messages

This functionality generates the following messages:

  • CASKC6002I JOBnnnnn terminated due to exceeding TIME parameter
  • JES000034E JOBnnnnn - TIME parameter exceeds 65533 after applying class multiplier (nnnn)

Parent topic: Configuring JCL Timeouts


CTF Tracing/CAS AUX Tracing

The following tracing functionality has been added:

  • The DISP property of mf.mvs.casspool ctf tracing has been enhanced to show the calculation for adjusted timeouts.
  • A trace has been added to the CAS Aux tracing for jobs that terminate due to a timeout. This trace is from the casmgr process, and shows the name of the job that timed out.
Parent topic: Configuring JCL Timeouts


JCL Aspects of Troubleshooting

This chapter covers some aspects of troubleshooting problems with running JCL applications in an MSS-enabled enterprise server.

  • Introduction
  • Consolidated Tracing Facility
  • MVSJOBNO
Parent topic: JCL Support


Introduction

Problem diagnosis on a JCL-enabled enterprise server is very similar to problem diagnosis on an enterprise server running Web services or EJB-type services, as described in the chapter Troubleshooting in the Enterprise Server Configuration and Administration Guide.

Parent topic: JCL Aspects of Troubleshooting


Consolidated Tracing Facility

The Consolidated Tracing Facility (CTF) allows you to produce diagnostic information detailing the operation of Micro Focus software components and your own programs.

Parent topic: JCL Aspects of Troubleshooting
Related information
Introduction to the Consolidated Tracing Facility


MVSJOBNO

If you get MVSJOBNO I/O error 42, delete the file mvsjobds.dat, which you will find in the same directory as your catalog, and then try the failed operation again.

Parent topic: JCL Aspects of Troubleshooting


Searching for Catalog Entries

Using wildcards

In the catalog search facility, you can use wildcards to receive a wider range of results. The search facility supports substitutions where you can specify a single wildcard (*) or double wildcards (**) or a combination of these - for example, *AA.**.B*B.

When using one or more wildcards in the dataset name field, the returned entries are limited to those that fall within the wildcard parameters. It is possible to use both a single * and multiple ** or a single * multiple times.

Using dots in search expressions

Using a dot, ., in your search expressions can affect the search results. The dot, ., is a significant character within a dataset name as it is a name node separator and, when used in a search expression, will be interpreted as such. This means that the returned results only have a certain number of nodes and the characters in those node names match the wildcard pattern passed for each node. If you receive unexpected results, check your use of the dot.

Using double wildcards

Specifying double wildcards, **, in search expressions helps avoid problems with interpreting the dots because the double wildcards indicate any number of modes. They indicate that any number of characters, including dots, may appear between the significant characters.

Examples

To demonstrate how this works, let's look at performing a few searches for the following example catalog:

MFITEST.AAA.01
MFITEST.BBB.01
MFITEST.CCC.01
MFITEST.DDD.EEE.01
  • A search for MFITEST*01 returns all catalog entries.
  • A search for MFITEST.*01 does not return any results.
  • A search for MFITEST.*.*01 returns the first three catalog entries.
  • A search for MFIT*.**.01 returns all catalog entries.
Parent topic: JCL Catalog Tasks


IMS Support

  • Creating and Configuring an Enterprise Server Instance for IMS
    Describes the creation and configuration of an enterprise server instance that runs an IMS application.
  • IMS Database Administration
    BTS Trace, IMS Database Locking and IMS Database Recovery.
  • WebSphere MQ Support
    Describes Enterprise Server support for communicating with WebSphere MQ to receive and process requests, and to return output back to WebSphere MQ.
Parent topic: MSS Configuration and Administration


Creating and Configuring an Enterprise Server Instance for IMS

To run IMS applications, you must create an enterprise server instance that is MSS-enabled and appropriately configured to run an IMS application. You can do this either from the Enterprise Developer IDE or Enterprise Server Administration. When you create the enterprise server instance from the Enterprise Developer IDE, much of the configuration is done for you; however, both methods require manual configuration as well.

Creating an enterprise server instance from Enterprise Developer using the IMS Template

Enterprise Developer provides an Enterprise Server template, IMSTemplate.xml, that you can use to simplify the process of creating and configuring an enterprise server instance for an IMS application. IMSTemplate.xml is located in by default. When you use the template to create the enterprise server instance, the following is enabled or configured for you automatically based on your Enterprise Developer project properties and the information you supply when creating the enterprise server:

Default configuration for an IMS-enabled enterprise server instance:
  • MSS is enabled
  • IMS is enabled
  • System Initialization Table is set to IMSSIT
  • Message processing region (MPR) is created
Configuration based on information required by the template:
  • Enterprise server instance name
  • Project is associated with enterprise server instance
  • Working mode, 32- or 64-bit
Configuration based on Enterprise Developer project properties:
  • Application path
  • Configuration directory
  • Database path
  • GEN file directory
  • Map/MFS path
  • Transaction path

You must manually specify a TN3270 listener and port number.

Creating and configuring an enterprise server instance from Enterprise Server Administration

When you create an enterprise server instance from Enterprise Server Administration with the intent to run an IMS application on the enterprise server, you must configure the following as a minimum:

When initially creating the enterprise server instance, specify:
  • A name for the enterprise server instance
  • Mainframe Subsystem Support
  • Working mode, 32- or 64-bit
  • Specify a TN3270 listener and port number
Manually configure the following:
  • Enable IMS
  • Specify a System Initialization Table (SIT)
  • Specify the location of:
    • Application files
    • Database files
    • Generated files
    • Maps/MFS files
    • Transaction files
  • Specify a message processing region (MPR)
Optional IMS configuration:
You can also configure the following, based on the needs of your IMS application:
  • If your IMS application contains JCL, you must also configure the enterprise server for JCL
  • If you want to use IMS Connect to connect to the database, enable IMS Connect
  • Create a resource group
  • Add a resource group to a startup list
  • Define transactions
  • Calculate shared memory area requirements
  • Specify printers
Important:
  • Migrated IMS applications do not require that you define services, request handlers or implementation packages; however, you should not delete the system services and request handlers that are automatically associated with an enterprise server when you create it.
  • Resources, SITs and startup lists are all CICS concepts. However, our IMS support in Enterprise Server is closely integrated with support for CICS, and as a result, much of the configuration necessary to run CICS applications in an enterprise server is also necessary to run IMS applications. If you are not familiar with CICS concepts, we suggest you read MSS and CICS Support before continuing.
  • Our Enterprise Server product includes many tools and features you can use with IMS applications but that are not specific to IMS applications. Read the Configuration and Administration section to become familiar with other features you might find useful.
  • MSS and CICS Support
  • IMS Connect
  • Open Transaction Manager Access (OTMA)
  • IMS-enabled Enterprise Server Administration using ESMAC
  • Defining IMS Resources
  • Defining IMS Transactions
  • Configuring the IMS Message Queue
  • Configuring IMS Printers
  • Calculating Shared Memory Area Requirements
Parent topic: IMS Support
Related concepts
Configuring Enterprise Servers for JCL
Related tasks
To define specific printers for an IMS-enabled enterprise server
To enable printer security for an IMS-enabled enterprise server
To attach to an IMS printer
Printers
To create an IMS-enabled enterprise server from the Enterprise Developer IDE
To create an MSS-enabled enterprise server for IMS applications from Enterprise Server
To enable MSS for an existing enterprise server
To enable IMS for an MSS-enabled enterprise server
To specify the location of generated files
To specify the location of application files


MSS and CICS Support

This section provides a brief overview of the CICS concepts with which you need to be familiar in order to configure enterprise server for use with IMS. This is necessary because support for IMS in Enterprise Server is integrated with support for CICS. If you are familiar with basic CICS concepts you can skip this section.

In CICS, items of software or hardware for use by applications are called resources. Mainframe Subsystem Support adds to Enterprise Server facilities for defining, controlling and monitoring resources. These facilities have been extended to include resources needed by IMS applications. You don't need CICS experience to use these, but you do need a basic understanding of the structure, so for readers unfamiliar with the CICS model, here is a quick overview.

In CICS, you define sets of resources. These sets of resources are called resource groups.

A CICS region is an environment for running CICS applications. When you create a region, you specify a system initialization table (SIT), which gives details of how the region is to be configured. One item specified by the SIT is called a startup list; this is a list of resource groups that are to become available automatically when the region is started.

An enterprise server is equivalent to a CICS region, in Enterprise Server for Windows or UNIX. To run IMS applications, you need to define special service execution processes (SEPs) called message processing regions (MPRs). You define these MPRs as CICS-style resources. Resources always belong to resource groups, so you also need to define a resource group, which needs to be referenced by a startup list, which needs to be referenced by a system initialization table (SIT). You then need to specify that the enterprise server is to use this SIT.

The figure below shows the hierarchical structure of SITs, startup lists, resource groups, and individual resources. The bottom line of the figure shows some more types of CICS resources - a program control table (PCT), file control table (FCT) and program processing table (PPT).

Figure 1. Structure of CICS Resources
Structure of CICS Resources

For more information about CICS Support within MSS, see Part 2 of this book. For more information about Enterprise Server, see your Enterprise Server Configuration and Administration Guide.

Parent topic: Creating and Configuring an Enterprise Server Instance for IMS


IMS Connect

IBM IMS Connect is an add-on product to mainframe IMS that provides TCP/IP connectivity to IMS/TM applications. IMS support in Enterprise Server includes emulation of IMS Connect to allow TCP/IP clients to connect for debugging of IMS/TM transactions.

The following IMS features are supported:

  • Conversational (SPA) and non-conversational transactions that do not use the IMS SETO functionality
  • Support for IMS commands
  • Security for all IMS Connect listeners
  • The following IBM-supplied I/O exits:
    • HWSIMSO0 '*IRMREQ*' Yes
    • HWSIMSO1 '*IRMRE1*' Yes
    • HWSSMPL0 '*SAMPLE*' Yes (unmodified - same as HWSIMSO0)
    • HWSSMPL1 '*SAMPL1*' Yes (unmodified - same as HWSIMSO1)
    • HWSJAVA0 '*HWSJAV*' Yes (unmodified)
    • HWSCSLO0 '*HWSCSL*' No
    No exit screening configuration is provided.
  • The return MOD name control
  • Persistent, non-persistent and transactional socket control
  • End-to-end ASCII flows

There is limited support for flow control and Syncpoint/Commit controls

The following are not supported:
  • Modified Sample I/O exits or target resolution exits
  • The return OTMA headers control
  • UTF and UCS codesets
  • The Translate control
  • The IRM timer
  • The One Message and One Message No Wait" controls
  • The Auto Flow and no Auto Flow controls
  • Asynchronous and unsolicited output to an IMS Connect client
Parent topic: Creating and Configuring an Enterprise Server Instance for IMS
Related tasks
To enable IMS Connect


Open Transaction Manager Access (OTMA)

If you are using Open Transaction Manager Access (OTMA) to communicate with IMS, no special configuration is needed. However you can specify the amount of time that an OTMA client should wait for an MPR to process a message. The default is 120 seconds, but you can change this period using the environment variable ES_OTMA_TIMEOUT.

The Enterprise Server OTMA C/I (Call Interface) supports the following calls:
CALL FUNCTION otma_create
Creates storage structures to support communications but does not establish a connection with IMS.
otma_open
Establishes a connection with IMS. Issue an otma_create before establishing an otma_open call.
otma_alloc
Creates an independent transaction session.
otma_send_receive
Sends to IMS and passes parameters for receive functions.
otma_free
Releases the independent transaction session.
otma_close
Ends the connection with IMS.
Parent topic: Creating and Configuring an Enterprise Server Instance for IMS


IMS-enabled Enterprise Server Administration using ESMAC

We provide the Enterprise Server Monitor and Control (ESMAC) feature as the primary tool to run and monitor production applications, including IMS applications. We suggest that you read and become familiar with group of topics in the Administering Enterprise Server Instances using ESMAC section of this documentation.

When you first view ESMAC for an IMS-enabled enterprise server, the Server Information page is displayed, as shown here:

Figure 1. ESMAC Server information page for IMS
ESMAC Server information page for IMS

When you run ESMAC on an IMS-enabled enterprise server, you can use it to perform a wide range of administrative functions. Because of the integration between support for IMS and CICS within Enterprise Server, most of these administrative functions are described in the topic Administering CICS-enabled Enterprise Servers. In addition, you can use ESMAC to create temporary MPRs.

Parent topic: Creating and Configuring an Enterprise Server Instance for IMS
Related concepts
Defining IMS Resources
Related tasks
To Start ESMAC for an enterprise server instance
To create a resource group
To modify a resource


Defining IMS Resources

Enterprise Server IMS support includes two transactions, /CIC and /IMS, that you use to switch enterprise servers to CICS and IMS modes respectively. For these transactions to be available, you need to update your resource definition file at an Enterprise Developer command prompt using the caspcupg command as follows:

caspcupg /dp=resourcedefinitionpath /o

where resourcedefinitionpath is the path to the system resource definition file to be updated. If you are using the default system resource defintion file, dfhdrdat located by default in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\cas , you can omit /dp=resourcedefinitionpath. See caspcupg for more information on the caspcupg command.

Updating a resource definition file with the /CIC and /IMS transactions in this way is a one-off process, meaning that once you have used caspcupg to upgrade a resource definition file, any enterprise server that uses the updated resource definition file can use the new transactions.

Resource Group

Before you can run an IMS application in an enterprise server you ensure that the following resources are included in a resource group:

Transactions
You must add a list of all transactions and their associated programs to a resource group. This is done by adding a PCT.
Messages
Add the message processing regions that the enterprise server uses.
Message Processing Region (MPR)

To run an IMS application in an enterprise server you need at least one specialized service execution process (SEP) called a message processing region (MPR). To specify that a message processing region starts each time an enterprise server starts, it must be included in a resource group that is specified by the startup list in the SIT used by the enterprise server.

You can add these resources to an existing resource group or create a new one for them.

Startup Lists

Having created a resource group for the resources needed by your IMS application, you need to add the resource group to a startup list.

Note: To update a resource group or startup list, you must first start the enterprise server then use Enterprise Server Monitor and Control (ESMAC). See Administering Enterprise Server Instances using ESMAC for more information on using ESMAC.
Parent topic: Creating and Configuring an Enterprise Server Instance for IMS
Related concepts
IMS-enabled Enterprise Server Administration using ESMAC
Related tasks
To Start ESMAC for an enterprise server instance
To create a resource group
To modify a resource
To define a transaction manually
To add a resource group to a startup list
Related reference
caspcupg


Defining IMS Transactions

Usually, a transaction definition must exist for any program you want to run. There are two ways of creating transaction definitions:

  • Define them manually using Enterprise Server Monitor and Control (ESMAC)
  • Use the transaction export and import utilities to extract IMS transactions from an IMS stage 1 file downloaded from the mainframe, or from transaction file created from an enterprise server instance, and automatically add the transactions to your enterprise server instance. This is a two-step process.
Exporting
You export transaction definitions to a transaction file, which contains the transaction and printer definitions needed to subsequently import into Enterprise Server. It is a flat text file, so you can edit it to remove any definitions that are not needed for the application to run under Enterprise Server. You can create a transaction file in one of two ways: Either export from a stage 1 file from the mainframe, or export the transactions from a different enterprise server instance.
Importing
The import utility reads the transaction file created by the export utility, and adds the transaction definitions to the IMSGEN2.DAT file in the current directory. If IMSGEN2.DAT doesn't exist, it is created.
Parent topic: Creating and Configuring an Enterprise Server Instance for IMS
Related tasks
To export IMS transactions
To import IMS transactions
To define a transaction manually


Configuring the IMS Message Queue

You can configure the IMS message queue to best serve the application or applications that run in an enterprise server region. You can modify default settings before starting the region. Once started, some of these settings are static, meaning that changes cannot be applied until the region is restarted. Others are dynamic, meaning that you can change and apply the settings without restarting the region.

Most IMS message queue options can be set from the Enterprise Server Administration Server > Properties > MSS > IMS > TM > General page. See Server Instance Properties: MSS IMS TM General for a detailed description of each option including default values.

Static Options

Before starting your enterprise server region, you can replace the default for any static IMS message queue option with an alternative initial setting. Static IMS message queue configuration options include:

  • (Message queue) Name
  • Queue buffer count
  • MFS path
  • MFS attribute bias
  • MFS null character
  • Application path

After starting the region, any changes made to these settings cannot be applied until the region is restarted.

Dynamic Options

Just as with the static options, you can use the default or provide a custom initial value for most dynamic IMS message queue options. However, you can also change the value of a dynamic option while the enterprise server region is running, with the new value taking effect immediately. You can:

  • Adjust the data store size limit
  • Adjust the data store allocation cushion size
  • Adjust the length of time that a transaction can run
  • Adjust the generation frequency of keypoints
  • Tune the flush aggregation performance behavior

You can assign an initial value for the following dynamic settings from the Enterprise Server Administration Server > Properties > MSS > IMS > TM > General page:

  • Maximum Blocks
  • Activity keypoint frequency
  • Transaction threshold

The initial configuration for other dynamic IMS message queue options are based on the values set by ES_TMC_AGGREGATE environment variable.

Once the enterprise server region is started, you can make changes to dynamic IMS message queue options from ESMAC on the IMS Control page.

The following topics provide additional details for dynamic IMS message queue configuration:

  • Dynamic IMS Message Queue Expansion
    Describes the dynamic IMS message queue expansion feature.
  • Dynamic IMS Message Queue Performance Tuning
    Describes using the ES_TMC_AGGREGATE environment variable to set an initial IMS message queue performance level, and using ESMAC to then fine-tune its performance dynamically.
Parent topic: Creating and Configuring an Enterprise Server Instance for IMS
Related reference
Server Instance Properties: MSS IMS TM General
IMS Control


Dynamic IMS Message Queue Expansion

In earlier versions of Enterprise Server, the Maximum blocks size as specified for an enterprise server region on the Enterprise Server Administration Server > Properties > MSS > IMS > TM > General page was a static allocated message queue size on a cold start. Subsequent changes had no effect until the execution of the next cold start.

Starting with Enterprise Server version 2.3, Maximum blocks specifies a size limit to which the message queue data store can expand. The initial (default) allocation is always the minimum number of blocks required, meaning the number of blocks initially allocated is equal to or greater than the number of buffers specified in the Queue buffer count. As the application runs, blocks are allocated and formatted as needed up to this limit.

In addition to increasing the size of the data store, you can also modify the percentage of allocated blocks to reserve as a cushion that provides enough emergency allocation space to enable graceful intervention should it be required due to lack of space.

The Maximum blocks specification is initially set to a default value of 32 blocks by Enterprise Server Administration. You can optionally alter this value before starting your enterprise server region. Once started, you can optionally increase the number of blocks and the cushion size, and apply the new settings from the IMS Control page in ESMAC while the region is running.

At any time, you can effectively reduce the maximum number of blocks down to the size of the current message queue physical allocation. Once physically allocated, message queue space cannot be reduced dynamically. This requires a cold start.

At startup, if the maximum size set in Enterprise Server Administration is smaller than the current physical message queue size, the maximum size is set to the message queue physical size.

After startup, you can adjust the maximum message queue size to any size starting with the number of blocks that represent the physical size of the current message queue, and up to the architectural limit of 63488 blocks.

Parent topic: Configuring the IMS Message Queue
Related tasks
To dynamically adjust the IMS message queue configuration
To enable dynamic IMS message queue performance tuning
Related reference
Server Instance Properties: MSS IMS TM General
IMS Control


Dynamic IMS Message Queue Performance Tuning

By default, the Enterprise Server TM system unilaterally flushes operating system buffers to your physical disk at key transactional points. These flushes are required to guarantee the transactional integrity of the message queue in the event of a failure that abnormally stops Enterprise Server TM. The overhead required for this default behavior can significantly degrade performance. However, you can improve performance by setting alternative options at startup, and by adjusting those options on the fly.

ES_TMC_AGGREGATE environment variable

To initialize performance settings for the IMS message queue, and to enable dynamic performance tuning, we provide the ES_TMC_AGGREGATE environment variable. Specifically, its twofold purpose is to:

  • Specify, at startup, either the default or an alternative method for flushing operating system buffers to disk.
  • Enable you to dynamically change the flushing method and apply it to the message queue without having to restart the enterprise server region.

Set ES_TMC_AGGREGATE for a specific enterprise server region by adding it to the [ES Environment] section in the Configuration Information field located on the Administration Server > Properties > General tab. Use the following syntax:

[ES-Environment]
ES_TMC_AGGREGATE={[,N|,D]|nnn,Y}
,N
Sets the default behavior, which is to unilaterally flush operating system buffers to your physical disk at each key transactional point. While this does not change the method used by default at startup, it does enable dynamic modification via ESMAC. Once set, you can then test the effect of various non-default settings by altering them dynamically.
,D
Disables the transactional flushing of operating system buffers to disk. This option can significantly enhance message queue performance; however it is at the expense of the transactional integrity of the message queue in the event of a system failure.
Note: To avoid unpredictable results when using this setting, we highly recommend that you also set the static options as follows on the Administration Server > Properties > MSS > IMS > TM > General tab:
  • Set Cold start to Everything (queue)
  • Check Persist

See Server Instance Properties: MSS IMS TM General for details.

nnn,Y
Enables the aggregated transactional flushing of operating system buffers to disk where nnn represents an interval of time, in milliseconds, during which additional buffers are allowed to accumulate before flushing. Valid values are 0 through 255.

Once a thread reaches a key transactional point and requests a flush, TM waits the specified interval to accumulate subsequent threads that also request a flush. At the end of the interval, one flush is performed for all accumulated requests thus potentially improving performance by reducing the number of flush commands issued to the operating system.

Note:
  • Threads requesting a flush wait until the flush is confirmed.
  • Generally, when the message queue resides on a higher performance I/O subsystem such as one using SSDs, a smaller value, e.g. 1 or 2, produces the best results. A value of 10 or higher seldom improves performance.

Dynamic changes using ESMAC

You can adjust and apply IMS message queue performance settings dynamically from the TM System Overview and Control section on the ESMAC IMS Control page. Use this feature to test various performance settings, and to adjust performance on the fly when required.

Important: Performance results produced by the ES_TMC_AGGREGATE environment variable settings and the associated dynamic ESMAC settings are strictly dependent on the hardware and operating system on which Enterprise Server is running. Test rigorously before committing these settings to a production system.
Parent topic: Configuring the IMS Message Queue
Related tasks
To enable dynamic IMS message queue performance tuning
To dynamically tune IMS message queue performance
To dynamically adjust the IMS message queue configuration
Related reference
IMS-Specific Environment Variables
Server Instance Properties: MSS IMS TM General
IMS Control


Configuring IMS Printers

Enterprise Server supports LU1 and LU3 printers for use with enterprise servers configured to run IMS applications, and is specifically limited to printer clients that support the TCP TN3270 protocol. Non-TN3270 printer clients and the IMS Spool interface are not supported.

Prerequisites

Before configuring a printer, you must have an MSS-enabled enterprise server defined in Enterprise Server Administration. Once this is in place, do the following:
  • Specify a system initialization table
    We recommend that you either specify the provided SIT, IMSSIT, or that you copy the IMSSIT to another name and specify the newly copied SIT. IMSSIT is preconfigured with many of the requirements necessary to run a successful IMS application, including:
    • Initial Tran ID - This is set to /IMS, and specifies that interactive TN3270 clients initially connect to IMS TM.
    • IMSSTRT Startup List - Includes several resource groups that provide a number of resource definitions required for the basic operation of Enterprise Server. Group IMSGRP contains resource definitions that are specific to Enterprise Server and IMS operation.
    • IMSGRP Resource Group - Contains a TERM model definition for LU1 printers.
  • Ensure that your SIT is updated with current printer definitions

    When you upgrade from an earlier version of Enterprise Developer, user-specific resource groups such as IMSGRP are not updated automatically. We recommend that you add the current printer definitions manually. Do this by running the following command at an Enterprise Developer command prompt:

    caspcupg /o

Enabling Printer Support

The procedure for enabling printer support varies depending on your needs. Consider the following use case scenarios:

Use Case 1: Most or All Printers are LU1
No further configuration is required unless some printers are LU3 (see Use Case 3 below).
Use Case 2: Most or All Printers are LU3
In this case, rename the MLU1 printer Term Model definition in the IMSGRP resource group to MLU3, and redefine it as Term Model specifically for LU3 printers.
Important: You must rename and reconfigure the MLU1 definition, or remove it and create a new definition for LU3 printers. We do not support multiple Term Model printer definitions for TN32871.
Use Case 3: Define Specific Printers to Enterprise Server
In this case, you want to install explicit definitions for exceptions to Use Case 1 or 2, or for all printers. This requires that you add the printer definition or definitions to the IMSGRP resource group by adding a Term definition for each printer.

Additional Configuration

In addition to defining your printers, you must also configure the following:
  • Define the printer to Enterprise Server security
  • Configure your TN3270 emulator to attach to the printer

Assigning Client Names

In the process of configuring printers for an IMS-enabled enterprise server, you must provide a client name and other names in several areas of configuration. This can be tricky. Consider the following as you complete the configuration process:
  • The TN3270 client name is ultimately the IMS LTERM name that identifies the printer.
  • This client name must also appear in the Enterprise Server security system as a user ID. The printer operates under Enterprise Server with the security authorization assigned to this user ID.
  • When attached to Enterprise Server, this client name appears as the printer's Net Name on the Enterprise Server ESMAC Clients page.
  • If this client name/Net Name is not defined to Enterprise Server with a specific TERM definition, it is assigned the characteristics of the Enterprise Server TERM model definition with the model name of TN32871.
  • The TN3270 printer emulator Terminal Type definition must default to or be specified as IBM-3287-1. The TN3270 client name and terminal type are the controlling definitions.
  • Associated Enterprise Server definitions are used if they match the names specified in the TN3270 client.
Parent topic: Creating and Configuring an Enterprise Server Instance for IMS
Related tasks
To define specific printers for an IMS-enabled enterprise server
To attach to an IMS printer
To enable MSS for an existing enterprise server
To enable IMS for an MSS-enabled enterprise server
To start an enterprise server instance
To Start ESMAC for an enterprise server instance


Calculating Shared Memory Area Requirements

The shared memory area calculation for an IMS-enabled enterprise server is essentially the same as for a Web services enterprise server. Your calculation should also include 512 bytes for each 3270 client that is connected to the enterprise server. You must include your message processing regions in the total number of service execution processes.

If you are using CICS or JCL applications in the same enterprise server, in addition to the IMS calculation, perform the calculations described in the Shared Memory Area topics pertaining to CICS and JCL. Add the relevant results to the figure you calculated for IMS.

Parent topic: Creating and Configuring an Enterprise Server Instance for IMS


IMS Database Administration

  • BTS Trace
    Describes the BTS trace feature, which enables you to view DL/I API calls and parameters issued by an IMS application.
  • IMS Database Locking
    Describes the tools available to lock your IMS database.
  • IMS Database Recovery
    Describes the options available for recovering a corrupted IMS database.
  • IMS Checkpoints
    Describes the IMS checkpoint functionality
Parent topic: IMS Support


BTS Trace

The BTS trace feature logs DL/I API calls and parameters issued by an IMS application. You enable BTS trace from JCL. When JCL SSTM support is enabled, you can use the BTS trace feature to also trace IMS transactions, CICS transactions, and batch programs from CRUN.

Enable BTS Trace

You enable BTS trace from JCL using the following DD specifications:
IMSTRACE
Defines the output data set for the BTS trace. SYSOUT=* directs BTS output to the job. You can also direct output to a data file by specifying DCB=(RECFM=LSEQ,LRECL=80,DSORG=PS).
BTSCONFG
Enables control of BTS trace output options, and takes the following keywords:
SSA | Include segment search arguments, if any
PCB | Include the PCB area
PCBHELP | Include help text in the trace for invalid SSAs (AJ DL/I status code)
IOAREA | Include input-output buffer
STATS | Include call statistics
TIMES | Include call timings for performance measurement
DIAG | Include detailed diagnostic information
LISTFILE | In addition to the specified output data set, write BTS trace output to a compressed file named BTS-nnn.LST, where nnn is the process ID in decimal

These specifications apply to the current job step only, and override any BTS trace flags stored in the IMSCONFG.DAT configuration file.

Examples

Sample JCL
This sample JCL enables BTS trace in an IVP program named DEMO001B:
//S01       EXEC PGM=DFSRRC00,REGION=4M,
//          PARM='BMP,DEMO001B,DEMO001T,,,,,,,,,CDLI,,N,N'
//REPORT1   DD SYSOUT=*
//IMSERR    DD SYSOUT=*
//PRINTDD   DD SYSOUT=*
//SYSOUT    DD SYSOUT=*
//SYSPRINT  DD SYSOUT=*
//IMSTRACE  DD SYSOUT=*
//BTSCONFG  DD *
SSA
PCB
IOAREA
/*
//
Sample BTS output
This sample BTS output is from the DEMO001B program, and shows the DL/I call function, SSAs, PCB, and I/O area:
CBLTDLI:  ~~~~~~~~----+----1----+----2----+----3----+----4----+----5
CBLTDLI:  CALL   :GN
CBLTDLI:          4422
CBLTDLI:          7E00
CBLTDLI:  SSAS   : NONE
CBLTDLI:  PCB-003:DEMO03DD01  AP  ....DEMOHDRS...(............TEST
CBLTDLI:          44443344332245220000444444550002000000000000545522
CBLTDLI:          45DF034401001000000045DF84230008000200000000453400
CBLTDLI:
CBLTDLI:          22222222222222222222222222
CBLTDLI:          00000000000000000000000000
CBLTDLI:  IO AREA:........TEST                            Element Ta
CBLTDLI:          00000000545522222222222222222222222222224666667256
CBLTDLI:          00000000453400000000000000000000000000005C5D5E4041
CBLTDLI:          ble - Metals
CBLTDLI:          66622246766722222222222222222222222222222222222222
CBLTDLI:          2C50D0D541C300000000000000000000000000000000000000
CBLTDLI:                              ......N          .`0.
CBLTDLI:          22222222222222222222000000422222222220631222
CBLTDLI:          000000000000000000001C5C0CE0000000000000F000
CBLTDLI:  ~~~~~~~~----+----1----+----2----+----3----+----4----+----5
CBLTDLI:  CALL   :GN
CBLTDLI:          4422
CBLTDLI:          7E00
CBLTDLI:  SSAS   : NONE
CBLTDLI:  PCB-003:DEMO03DD02  AP  ....DEMOELES...F............TEST
CBLTDLI:          44443344332245220000444444450004000000000000545522
CBLTDLI:          45DF034402001000000045DF5C530006000200000000453400
CBLTDLI:                                    ..........Ag
CBLTDLI:          22222222222222222222222222000000000046222222222222
CBLTDLI:          00000000000000000000000000000000000017000000000000
CBLTDLI:
CBLTDLI:          222222
CBLTDLI:          000000
CBLTDLI:  IO AREA:..........Ag                  Silver
CBLTDLI:          00000000004622222222222222222256676722222222222222
CBLTDLI:          00000000001700000000000000000039C65200000000000000
CBLTDLI:
CBLTDLI:          22222222222222222222222222222222222222222222222222
CBLTDLI:          00000000000000000000000000000000000000000000000000
CBLTDLI:                    (    1 line(s) same as above )
CBLTDLI:                       ........
CBLTDLI:          22222222222220000000022222222222222222222222222222
CBLTDLI:          00000000000000000000C00000000000000000000000000000
CBLTDLI:
CBLTDLI:          222222222222222222222222
CBLTDLI:          000000000000000000000000
Parent topic: IMS Database Administration


IMS Database Locking

The type of database locking used for Enterprise Server applications that access IMS databases is based on their access mode, which can be either exclusive or shared.

Exclusive Access Mode Locking

Exclusive access mode is used for administration tools, utilities and batch application programs. Exclusive access locks an IMS database at the database level. The database is in non-sharing mode and available to a single process only. This access requires that the database is in a stopped state in Enterprise Server. Examples of exclusive access processes are:
IMS Database Editor tool
The tool is available only from the Enterprise Developer IDE and exclusively owned by the IDE process.
IMS Database Utility (IMSDBU)
Accessible from JCL, the command line, or the Enterprise Developer IDE. The IMS database data is opened exclusively by IMSDBU and owned by the process where IMSDBU was invoked.
Batch application program
A DLI or DBB batch application program running in a JES initiator uses the IMS Database Control process to open the database data exclusively on behalf of the application program running in a JCL initiator. In addition, you can use one of the following:
IMSLOCK DD statement
Enables you to direct batch program execution to process all IMS DB calls entirely in the JES initiator, providing significant performance improvement. To use this feature, add the following to your JCL:
//IMSLOCK DD *
(EXCLUSIVE | SHAREDGO)
/*
EXCLUSIVE
  • Highest performance batch
  • Requires exclusive access to the database
  • Does not allow GO sharing
  • Equivalent to setting the ES_IMS_ LOCALDLI environment variable
SHAREDGO
Shared get only (dirty read). Default.
ES_IMS_LOCALDLI environment variable
Deprecated. Directs batch program execution to process all IMS DB calls entirely in the JES initiator. All IMS DB control processes accessed from the batch program must be stopped before execution because they become exclusively owned by JES until the program completes.

Shared Access Mode Locking

Shared access mode is used for online programs such as IMS and CICS transactions and IMS BMPs.

Requirements

Shared access requirements are:

  • The application accessing the IMS database is running in an enterprise server instance
  • The database is not in a stopped state
The following are some examples of shared access:
  • IMS Transactions (MPP)
  • Batch message processing programs (BMP)
  • CICS transactions and batch programs from CRUN
  • ODBA applications from JES initiator using AERTDLI or DDBA interface

Locking

In shared access mode, IMS database locking occurs at the database record level. The DB record includes the root segment and all dependent segments. Secondary Index DBs lock the DB record of the target segment in the primary database. Logical relationships lock both the DB record where the logical child segment is defined and the DB record of the destination parent.

If a locked record is encountered while processing a DLI call, DB Control goes into lock retry. This retry continues until either the record lock is released or a wait time is exceeded. The wait time is controlled by environment variable:

 ES_IMS_LOCK_TIMEOUT=n

Where n is expressed seconds in the range of 0-65535. The default value is 30 seconds. A value of 0 indicates to wait forever.

The lock retry algorithm can also be tuned for performance. This delay interval controls the retry frequency and can be externally controlled by environment variable:

 ES_IMS_LOCK_RETRY_DELAY=n

Where n is expressed in milliseconds in the range of 0-65535. The default retry delay is 5 milliseconds.

When a lock wait period expires, a BD status code is returned to the DLI call and an error message written to the server console. It is not normal to have lock wait times expire; these should be researched. Possible causes for wait expirations are when an application holding locks is waiting on resources from another resource manager or suspended for some other reason. These can also happen when a system has become CPU starved due to other machine activity resulting in pausing of the application. This can be rectified by increasing the lock timeout value.

To help diagnose lock timeout issues, the following environment variable triggers a system dump when a timeout is detected:

 ES_IMS_DUMP_ON_TIMEOUT=1

Shared access databases can use one of two locking modes: traditional or IRLM. The locking mode is defined to IMS DB Control at Enterprise Server startup.

  • Traditional Locking
  • Internal Resource Lock Manager (IRLM)
  • Deadlocking
  • DB Control Queries
Parent topic: IMS Database Administration


Traditional Locking

Traditional locking is the default locking mode and requires no configuration to implement. It uses the locking functions of the Micro Focus file handler. Locks are placed dynamically on the root segment at time of access and held until the unit-of-work reaches a commit point.

Locks are placed for both read and update DLI calls with no distinction between read locks, update intent locks or update locks. This implements the highest application isolation, which results in increased data contention and greater risk of deadlock.

Parent topic: IMS Database Locking


Internal Resource Lock Manager (IRLM)

IRLM locking closely parallels mainframe IMS database DB locking behavior, reducing data constraint and potential for deadlock. Some benefits are:
  • Prevents multiple readers from blocking each other
  • Using passing scope lock release
  • Applications using a PCB that specifies PROCOPT=GO have no locking and no data constraint
  • Enabling IRLM Locking
  • IRLM Implementation
  • IRLM Lock Table Statistics
Parent topic: IMS Database Locking


Enabling IRLM Locking

To enable IRLM locking, you must set the following environment variable before starting your enterprise server instance:
ES_IMS_IRLM=1
Parent topic: Internal Resource Lock Manager (IRLM)
Related reference
IMS-Specific Environment Variables


IRLM Implementation

IRLM uses an IMS-specific lock table in DB Control. This lock table tracks locks by session using the database name and root segment relative-byte-address (RBA). This lock can define one of three lock states:

READ
Database record in use. Allows READ access from other sessions but blocks UPDATE-INTENT and UPDATE lock requests. If the application program PCB that issued the READ lock passes scope to another database record without updating any segments this READ lock is released.
UPDATE-INTENT
The database record is locked exclusively when accessed using a hold call (GHU, GHN, GHNP) which may be followed by a REPL or DLET call. If the application program PCB that issued the lock passes scope to another database record without updating any segments, this UPDATE-INTENT lock is released.
UPDATE
Database record has been updated via ISRT, REPL or DLET call and will remain locked until the application program reaches a commit point. These locks do not release on passing scope.
Parent topic: Internal Resource Lock Manager (IRLM)


IRLM Lock Table Statistics

From ESMAC, you can query lock table statistics using the following DB Control command:

/DIS DB /LOCK

A lock table query from ESMAC returns the:
  • Session ID
  • Relative PDB number
  • Lock type
  • Database
  • Relative byte address (RBA) of the locked database record

ESMAC Lock Table Query
Parent topic: Internal Resource Lock Manager (IRLM)


Deadlocking

IMS applications can deadlock, meaning that two or more programs cannot progress due to locking conflicts arising from accessing the same data resources at the same time, but in a different order. For example:

program-1 accesses segment-A, then segment-B

while at the same time,

program-2 access segment-B, then segment-A

This creates an AB-BA deadlock, halting progression for both applications.

Additional, more complex scenarios are also possible with three or more programs.

Resolving deadlock issues

The first line of defense against deadlocks is to avoid coding deadlock scenarios into your applications.

However, when a deadlock does occur, IMS DB Control can help by detecting deadlocks caused by contention for IMS database data.

Note: IMS DB Control does not detect deadlocks that involve multiple resource managers such as a data constraint between IMS DB and SQL.

When a deadlock occurs, DB Control chooses a loser and terminates the DLI call returning an FD status code. This FD status code triggers a system-issued ROLLBACK operation on behalf of the application program. IMS BMP and CICS programs receive the FD status code in response to the DLI call. IMS transactions automatically restart.

The deadlock loser is chosen based on the application type, number of DLI calls, and duration of execution. An IMS MPP is chosen before a CICS transaction, and a CICS transaction is chosen before a BMP. When the sessions involved in a deadlock are all of the same program type, the number of DLI calls in the current unit-of-work is compared and the session with the lowest number is chosen as the loser. If the number of DLI calls in the current UOW match, the session with the shortest duration is chosen as the loser.

By setting the ES_IMS_DEADLOCK_WAIT environment variable, you can delay the algorithm that tests for deadlocks. This ensures that DB Control threads don't spend CPU cycles at every data contention point:

 ES_IMS_DEADLOCK_WAIT=n

Where n is expressed in milliseconds in the range of 1-65535. The default value is 1000 milliseconds.

To help diagnose application deadlocks, the following environment variable triggers a system dump when a deadlock is detected.

 ES_IMS_DUMP_ON_DEADLOCK=1
Parent topic: IMS Database Locking
Related reference
IMS-Specific Environment Variables


DB Control Queries

From ESMAC, you can issue DB Control commands to view database statistics.
IMS DB Control status

Query IMS DB Control status using the command:

/DIS DB /STATUS

This returns various statistics for client sessions and DLI calls processed:
ESMAC Control Status

IMS DB Control session
Query the IMS DB Control session status using the command:

/DIS DB /SESSION

This returns various session statistics, including:

  • Session identifier (S-ID) - Corresponds to a JES initiator, MPP region or CICS SEP
  • Client process identifier (C-PID)
  • The ID of the process running the application
  • Control session status, which can be one of:
    Active | Thread actively processing the DLR call
    Idle | Thread idle waiting for application
    Blocked | Thread waiting on a blocked record
Additional statistics
In addition, the session query returns the:
  • Database
  • DLI function
  • Number of DLI calls in the current unit-of-work

If a session is blocked, the query also returns the:

  • RBA
  • Lock-holder session ID

ESMAC Session Query
Parent topic: IMS Database Locking


IMS Database Recovery

We provide several alternatives for recovering corrupted IMS databases:
  • Automatic Backward Recovery
  • Forward Recovery

To use Forward recovery, you must enable it. Backward Recovery is enabled by default. We recommend that you have both enabled, as together they provide the best coverage.

  • IMS Database Automatic Backward Recovery
    Describes the Backward Recovery feature used to protect the integrity of an IMS database.
  • IMS Database Forward Recovery
    Describes IMS database recovery using database image copies and forward recovery log files to restore the most recent database updates.
  • TLOG Files
    Describes the transaction log files (TLOGs) used in IMS database Backward and Forward recovery.
  • Rebuild Utility
  • IMS Batch Backout
  • Enterprise Server warm/cold start
Parent topic: IMS Database Administration


IMS Database Automatic Backward Recovery

Describes the Backward Recovery feature used to protect the integrity of an IMS database.

Automatic Backward Recovery is the first line of defense in protecting the integrity of an IMS database. It is the most expeditious method of restoring a database, thus minimizing the time that a particular database must be offline. Automatic Backward Recovery is disabled by default. When enabled, Enterprise Server invokes it automatically to check for and repair corrupted data when an IMS transaction or the IMS Database Engine fails, backing out uncommitted data for all databases specified in the unit of work, thereby restoring the database.

In addition, you can manually invoke Backward Recovery as a JCL job, or using the mfims imsdbu Rollback function from the command line. These options provide you with a means to control the time and circumstances under which a Backward Recovery is performed.

  • Automatic Backward Recovery Process
    Describes the Automatic Backward Recovery process.
  • Invoking Backward Recovery from JCL
    Describes how to invoke Backward Recovery from JCL.
Parent topic: IMS Database Recovery


Automatic Backward Recovery Process

Describes the Automatic Backward Recovery process.

By default, Automatic Backward Recovery is disabled.

Important: The handling of transaction log (TLOG) files for Backward Recovery differs depending on whether Forward Recovery is enabled or disabled. See TLOG Files for details.

Automatic Backward Recovery Disabled

During normal Enterprise Server startup or the restart of IMS Database Control, DBC determines whether or not the last execution of DBC shut down properly. If it did not, then DBC automatically scans the most current TLOG to determine if any databases require recovery. However, it does not initiate a recovery process. The name of each database that is determined to be corrupt is written to the ROLLBACK.LST file located by default in the %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\ESName directory, and DBC switches to a "suspend" mode. This means that normal transactional processing is prohibited. In this mode, DBC accepts only commands to recover, START, and STOP databases. In this case, you can manually recover any database from a JCL job or using the mfims imsdbu Rollback function. Once you have determined that all databases are properly recovered, use the /DBC RESUME command to restore DBC to full functionality. See IMS Database Control (DBC) Commands for more information.

Automatic Backward Recovery Enabled

You can enable automatic Backward Recovery by setting the ES_IMS_ROLLBACK environment variable in the configuration information for your enterprise server instance to 1. For example:
[ES-Environment]
ES_IMS_ROLLBACK=1

When started by a normal Enterprise Server startup or when triggered by an emergency, the IMS Database Control (DBC) process determines whether or not the last execution of DBC shut down properly. This is done by reading the DBC status file, IMSDBC.DAT, located by default in the %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\ESName directory. This file is updated with the status of each IMS database every time the database is shut down and each time its status changes.

When Enterprise Server starts up, DBC reads the most recent status for each database from the IMSDBC.DAT file and restores the databases that shut down normally to their most recent state.

If the IMSDBC.DAT indicates that one or more databases did not shut down properly, DBC invokes Backward Recovery automatically to restore each of those databases using the most recent transaction log (TLOG) file as input.

When recovery of all databases is complete, a summary of databases that were recovered and any warning or error messages returned during the recovery process are written to a list file, which by default is named ROLLBACK.LST and is located in the %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\ESName directory.

Note: If DBC is unable to read the IMSDBC.DAT file for any reason, DBC starts up in a "suspend" mode, meaning that normal transactional processing is prohibited. In this mode, DBC accepts only commands to recover, START, and STOP databases. In this case, you can manually recover any database from a JCL job or using the mfims imsdbu Rollback function. Once you have determined that all databases are properly recovered, use the /DBC RESUME command to restore DBC to full functionality. See IMS Database Control (DBC) Commands for more information.
Parent topic: IMS Database Automatic Backward Recovery
Related concepts
TLOG Files
Related reference
IMS Database Control (DBC) Commands


Invoking Backward Recovery from JCL

Describes how to invoke Backward Recovery from JCL.

To recover a database using JCL, you can invoke Backward Recovery.

To invoke Backward Recovery from JCL, include the following as part of a data SYSIN card:
TLOG=$ES_IMS_TLOG_PATH\tlogName.TLOG
where tlogName is the name of the TLOG file to be used in the recovery. For example:
//DBUJCL01 JOB 'IMS DATABASE UTILITY',CLASS=A,MSGCLASS=A
//*--------------------------------------------------------------------
//* Copyright (C) 1991-2010 Micro Focus (IP) Limited.
//* All rights reserved.
//*-------------------------------------------------------------------
//*
//* This job demonstrates using JCL to invoke Backward Recovery.
//*
//STEP01  EXEC PGM=MFDBUJCL,PARM='ROLLBACK'
//SYSOUT  DD SYSOUT=*
//SYSIN   DD *
TLOG=$ES_IMS_TLOG_PATH\DMOAPPL-13070111330849.TLOG
/*
//
Parent topic: IMS Database Automatic Backward Recovery


IMS Database Forward Recovery

Describes IMS database recovery using database image copies and forward recovery log files to restore the most recent database updates.

The process includes:

Preparing for Forward Recovery
  1. Run the Image Copy utility to make backups of all databases.
  2. Establish backup procedures to back up all databases at specified intervals moving forward.
  3. Enable forward recovery log files and set a location for generated log files.
  4. Establish backup procedures to back up all forward recovery log files at specified intervals moving forward.
Recovering IMS Databases
  1. Do one of the following:
    • Run the Image Restore utility to restore selected databases; then run the Recovery utility without specifying any image copy databases. This applies the updates from forward recovery log files to the databases found in the current location.
    • Run the Recovery utility specifying image copy databases. This restores the image copies and then applies the updates from forward recovery log files to the specified databases.
  2. Following each recovery done using the Recovery utility, always run the Image Copy utility to back up the recovered databases.
  • Preparing for Forward Recovery
    Describes procedures, prerequisites, and settings necessary for successful database recovery following a hardware or a system failure.
  • Image Copy Utility
    Describes the functions of the Image Copy utility and the JCL required to run it.
  • Image Restore Utility
    Describes the functions of the Image Restore utility and the JCL required to run it.
  • Recovery Utility
    Describes the functions of the Recovery utility, and the input and JCL required to run it.
Parent topic: IMS Database Recovery


Preparing for Forward Recovery

Describes procedures, prerequisites, and settings necessary for successful database recovery following a hardware or a system failure.

Back Up All Databases

Before you can recover a database, you must have a copy of it to restore. This requires that you perform database backups of all databases, and keep backup copies to use for recovery. Always back up your databases at predetermined recurring intervals. In the event that your database requires recovery, this can minimize the time required to restore the database, and minimizes risk when performing the recovery procedure.

Note: The Recovery utility always uses forward recovery log files to update an existing copy of the database even when, in certain situations, the restored backup copy is an empty, initialized database. Therefore, a backup copy of the database is always required for database recovery.

You can use any backup utility you choose. As an option, Micro Focus provides the Image Copy utility, which is part of our IMS Database Forward Recovery feature.

Important: Do not use any Micro Focus utilities on the backup image of a database before attempting to use the database copy for recovery. If you alter the database image in any way, the recovery fails.

Enable Forward Recovery Logging and Set Logfile Location

To use Forward Recovery, you must have the appropriate forward recovery log files in place. By default, forward recovery logging is turned off in Enterprise Server. Once enabled, Enterprise Server creates logs for all online database updates and for all database updates that occur as a result of executing a BMP transaction. To enable forward recovery logging and specify a location for generated forward recovery log files, include the following environment variables and settings in the [ES-Environment] specification entered into the Configuration Information field of Enterprise Server Administration for each enterprise server that updates an IMS database:

ES_IMS_ROLLFORWARD=YES
ES_IMS_TLOG_PATH=logFilePath
Important: Enterprise Server does not create forward recovery log files when databases are updated offline by batch programs running DLI or DBB mode. In these cases, we recommend that you create a backup of each affected database immediately following the completion of each batch job.

Set Up Log File Backup

Because the forward recovery log files are critical to database recovery, you must put something into place to back them up on a regular basis to preserve them. To successfully recover a database, all log files created by database activity that took place after the most recent database backup must be present for use by the recovery utility. All log files that contain records of database activity of any kind are required for a successful recovery, including log files that record only database query activity rather than database updates.

Never delete any log file until after the database has been backed up and you have verified that the log file is no longer needed.

Parent topic: IMS Database Forward Recovery


Image Copy Utility

Describes the functions of the Image Copy utility and the JCL required to run it.
The Image Copy utility copies all specified databases from their current location as defined by the ES_IMSDAT environment variable to a specified backup location. This is done using JCL that includes the following:
  • One STOP statement to stop each database you want to back up. All databases must be stopped before the Image Copy utility can back them up. For example:
    //STOP01    EXEC PGM=MFDBUJCL,PARM='/STO DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//STOP02    EXEC PGM=MFDBUJCL,PARM='/STO DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//STOP03    EXEC PGM=MFDBUJCL,PARM='/STO DB BNKACC'
//SYSOUT    DD SYSOUT=*
  • A JCL step to execute the Image Copy utility, IMAGECOPY. Optionally, you can also specify the VERIFY parameter to verify the contents of all copied databases. If a database is found to be corrupt, no copy is made. In this case, correct the problem by rebuilding the database before attempting to make another backup. The following example shows the VERIFY parameter in use:
    //IC       EXEC PGM=MFDBUJCL,PARM='IMAGECOPY,VERIFY'
  • Specify the name and location of each backed up database. The following example specifies that the copied databases be stored as GDGs, enabling you to keep multiple versions of the data:
    //BNKIC1   DD DSN=BNKTXN.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC2   DD DSN=BNKTXNX1.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC3   DD DSN=BNKCUST.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC4   DD DSN=BNKACC.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC5   DD DSN=BNKTXNX2.IC.GDG(+1),DISP=(NEW,CATLG)
  • In the SYSIN statement, list each database you want to copy followed by the name of the DD that represents the location of the backed up database. Place the database name in the first eight columns. For example:
    //SYSIN    DD *
BNKTXN       BNKIC1
BNKTXNX1     BNKIC2
BNKCUST      BNKIC3
BNKACC       BNKIC4
BNKTXNX2     BNKIC5

The following is a complete example of the JCL required to execute the Image Copy utility. It specifies that five databases, defined in the first eight bytes of SYSIN data, are to be copied to locations specified by the DD statements. Also, since the VERIFY parameter has been specified, an attempt is made to verify the integrity of the databases:

//RUNGDG JOB  'IC',CLASS=A,MSGCLASS=A
//*
//STOP01    EXEC PGM=MFDBUJCL,PARM='/STO DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//STOP02    EXEC PGM=MFDBUJCL,PARM='/STO DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//STOP03    EXEC PGM=MFDBUJCL,PARM='/STO DB BNKACC'
//SYSOUT    DD SYSOUT=*
//*
//IC       EXEC PGM=MFDBUJCL,PARM='IMAGECOPY,VERIFY'
//*
//SYSOUT   DD SYSOUT=*
//BNKIC1   DD DSN=BNKTXN.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC2   DD DSN=BNKTXNX1.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC3   DD DSN=BNKCUST.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC4   DD DSN=BNKACC.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC5   DD DSN=BNKTXNX2.IC.GDG(+1),DISP=(NEW,CATLG)
//SYSIN    DD *
BNKTXN       BNKIC1
BNKTXNX1     BNKIC2
BNKCUST      BNKIC3
BNKACC       BNKIC4
BNKTXNX2     BNKIC5
/*
//*
//START01  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//START02  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//START03  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKACC'
//SYSOUT    DD SYSOUT=*
//

If, for any reason, a database copy fails, the Image Copy utility creates an empty output dataset. In this case, you might want to delete the empty file before attempting to rerun the utility.

Important: Do not use any Micro Focus utilities on the backup image of a database before attempting to use the database image copy for recovery. If you alter the database image copy in any way, this causes the Recovery utility to fail.
Parent topic: IMS Database Forward Recovery


Image Restore Utility

Describes the functions of the Image Restore utility and the JCL required to run it.
The Image Restore utility copies a specified database image copy, overwriting the database with the same name, from the backup location to current location as defined by the ES_IMSDAT environment variable. If the ES_IMSDAT variable contains a concatenation of directories, each directory is searched for the matching database, and the database image copy is copied to the first directory found that contains a matching database. If the database is not found in any of the directories, the database image copy is copied to the first directory on the path.
Note: You can run the Image Restore utility to restore just the database, or you can restore the database and restore recent updates simultaneously using the Recovery utility.

An Image Restore job is run using JCL that includes the following:

  • One STOP statement to stop each database you want to restore. All databases must be stopped before the Image Restore utility can overwrite them. For example:
    //STOP01  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//STOP02  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//STOP03  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKACC'
  • A JCL step to execute the Image Restore utility, IMAGERESTORE. For example:
    //IC    EXEC PGM=MFDBUJCL,PARM='IMAGERESTORE'
  • Specify the name and location of each database you want to restore. The following example specifies that the copied databases are stored as GDGs, enabling you to keep multiple versions of the data:
    //BNKIC1   DD DSN=BNKTXN.IC.GDG(0),DISP=OLD
//BNKIC2  DD DSN=BNKTXNX1.IC.GDG(0),DISP=OLD
//BNKIC3  DD DSN=BNKCUST.IC.GDG(0),DISP=OLD
//BNKIC4   DD DSN=BNKACC.IC.GDG(0),DISP=OLD
//BNKIC5  DD  DSN=BNKTXNX2.IC.GDG(0),DISP=OLD
  • In the SYSIN statement, list each database you want to restore followed by the name of the DD that represents the location of the backed up database. Place the database name in the first eight columns. For example:
    //SYSIN    DD *
BNKTXN       BNKIC1
BNKTXNX1     BNKIC2
BNKCUST      BNKIC3
BNKACC       BNKIC4
BNKTXNX2     BNKIC5

The following is a complete example of the JCL required to execute the Image Restore utility. It specifies that five databases defined in the first eight bytes of SYSIN data are to be restored from the location specified by the DD statements to the location defined by the ES_IMSDAT environment variable:

//RUNGDG JOB  'IR',CLASS=A,MSGCLASS=A
//*
//STOP01  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//STOP02  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//STOP03  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKACC'
//SYSOUT    DD SYSOUT=*
//*
//IC    EXEC PGM=MFDBUJCL,PARM='IMAGERESTORE'
//*
//SYSOUT   DD SYSOUT=*
//BNKIC1   DD DSN=BNKTXN.IC.GDG(0),DISP=OLD
//BNKIC2  DD DSN=BNKTXNX1.IC.GDG(0),DISP=OLD
//BNKIC3  DD DSN=BNKCUST.IC.GDG(0),DISP=OLD
//BNKIC4   DD DSN=BNKACC.IC.GDG(0),DISP=OLD
//BNKIC5  DD  DSN=BNKTXNX2.IC.GDG(0),DISP=OLD
//SYSIN    DD *
BNKTXN       BNKIC1
BNKTXNX1     BNKIC2
BNKCUST      BNKIC3
BNKACC       BNKIC4
BNKTXNX2     BNKIC5
/*
//*
//START01  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//START04  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//START05  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKACC'
//SYSOUT    DD SYSOUT=*
//
Parent topic: IMS Database Forward Recovery


Recovery Utility

Describes the functions of the Recovery utility, and the input and JCL required to run it.
Note: You can also run the Recovery utility as an mfims imsdbu function. See the Recover function topic in your Enterprise Developer documentation for details.
Important: To successfully recover a database, all forward recovery log files containing records of all database activity that took place after the last database backup must be present for use by the Recovery utility. Log files must be unlocked to be used in recovery. To unlock log files, stop the server that created them.

The Recovery utility can restore image copy databases and/or the most recent database updates performed just before a hardware or a system failure.

Upon completion, the Recovery utility output file reports the number of updates applied to each recovered database, according to each recovery log file specified. The updates include the number of writes, rewrites, deletes, and so on.

To restore database image copies, the Recovery utility accepts as input the name and location of each database backup file. Optionally, before running this utility, run the Image Restore utility to copy any database image copy to the current location. To update a database with the most recent changes, the relevant log files must be available on the path specified by the ES_IMS_TLOG_PATH environment variable. The Recovery utility determines the relevant log files required to recover each database.

The utility can recover up to 200 databases in each JCL job. Be aware, however, if the date and timestamp on any given database is significantly older than the other specified databases, we recommend that you recover that database separately to save time. To do otherwise could cause the utility to process a large number of log files unnecessarily, ultimately degrading performance.

By default, when one execution of a database forward recovery job specifies multiple databases, and the Recovery utility cannot recover one or more of the databases specified, it attempts to recover the remaining databases. This can happen, for example, when a required forward recovery log file is missing. In this case, the Recovery utility recovers the databases for which all log files are found. Upon completion of the job, the job SYSOUT dataset contains information indicating the databases recovered and those not recovered.

Optionally, you can specify that the recovery should abend upon encountering the first error. To do this, insert the keyword ABEND as the first statement following the SYSIN JCL card. If the ABEND keyword is specified and the recovery encounters an error, no databases are recovered.

Note: If you want to preserve the state of your current databases before recovery, be sure to copy them elsewhere before running the Recovery utility.

The Recovery utility copies database images as specified in the DD statements to the current location before applying the updates from the forward recovery log files. The JCL includes:

  • One STOP statement to stop each database you want to recover. All databases must be stopped before the Recovery utility can recover them. For example:
    //STOP01  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//STOP03  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//STOP04  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKACC'
  • A RECOVER statement to execute the Recovery utility. This statement must include the RECOVER and the SERVER parameters. The RECOVER parameter simply executes the utility; SERVER is required, and names the server that created the log files. The utility uses only those logs that are necessary to restore the specified databases. For example:
    //RECOVER EXEC PGM=MFDBUJCL,PARM='RECOVER,SERVER=IMSBANK'
  • If you want to restore one or more database image copies and simultaneously restore the information in the forward recovery log files, specify the name and location of each database you want to restore and also use the SYSIN statement to list each database, followed by the name of the DD that represents the location of the backed up database. Place the database name in the first eight columns. For example:
    //BNKIC1   DD DSN=BNKTXN.IC.GDG(0),DISP=OLD
//BNKIC2   DD DSN=BNKTXNX1.IC.GDG(0),DISP=OLD
//BNKIC3   DD DSN=BNKCUST.IC.GDG(0),DISP=OLD
//BNKIC4   DD DSN=BNKACC.IC.GDG(0),DISP=OLD
//BNKIC5   DD DSN=BNKTXNX2.IC.GDG(0),DISP=OLD
.
.
.
//SYSIN    DD *
ABEND
BNKTXN       BNKIC1
BNKTXNX1     BNKIC2
BNKCUST      BNKIC3
BNKACC       BNKIC4
BNKTXNX2     BNKIC5
  • If you have previously restored the necessary databases using the Image Restore utility or any other database recovery utility, use the SYSIN statement to list each database you want to restore using forward recovery log files only:
    //SYSIN    DD *
ABEND
BNKTXN
BNKTXNX1
BNKTXNX2
BNKCUST
BNKACC

The following examples show the complete JCL required to execute the Recovery utility:

Example 1 - Restore database image copies, and database updates from forward recovery log files

//RUNGDG JOB  'RECOVERY',CLASS=A,MSGCLASS=A
//*
//STOP01  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//STOP03  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//STOP04  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKACC'
//SYSOUT    DD SYSOUT=*
//*
//*
//RECOVER EXEC PGM=MFDBUJCL,PARM='RECOVER,SERVER=IMSBANK'
//*
//SYSOUT   DD SYSOUT=*
//BNKIC1   DD DSN=BNKTXN.IC.GDG(0),DISP=OLD
//BNKIC2   DD DSN=BNKTXNX1.IC.GDG(0),DISP=OLD
//BNKIC3   DD DSN=BNKCUST.IC.GDG(0),DISP=OLD
//BNKIC4   DD DSN=BNKACC.IC.GDG(0),DISP=OLD
//BNKIC5   DD DSN=BNKTXNX2.IC.GDG(0),DISP=OLD
//SYSIN    DD *
ABEND
BNKTXN         BNKIC1
BNKTXNX1     BNKIC2
BNKCUST       BNKIC3
BNKACC         BNKIC4
BNKTXNX2    BNKIC5
/*
//*
//START01  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//START04  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//START05  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKACC'
//SYSOUT    DD SYSOUT=*
//*

Example 2 - Restore only database updates from forward recovery log files

//RUNGDG JOB  'RECOVERY',CLASS=A,MSGCLASS=A
//*
//STOP01  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//STOP03  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//STOP04  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKACC'
//SYSOUT    DD SYSOUT=*
//*
//*
//RECOVER EXEC PGM=MFDBUJCL,PARM='RECOVER,SERVER=IMSBANK'
//*
//SYSOUT   DD SYSOUT=*
//SYSIN    DD *
ABEND
BNKTXN
BNKTXNX1
BNKTXNX2
BNKCUST
BNKACC
/*
//*
//START01  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//START04  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//START05  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKACC'
//SYSOUT    DD SYSOUT=*
//*
Parent topic: IMS Database Forward Recovery


TLOG Files

Describes the transaction log files (TLOGs) used in IMS database Backward and Forward recovery.

TLOG File Properties

You specify the properties for TLOG files using the following environment variables:

ES_IMS_DB_TLOG_WRITETHRU
When set to 0 (zero), forces the flushing of TLOG buffers to disk on COMMIT only (default). When set to 1, forces the flushing of TLOG buffers to disk on all database I/O.
ES_IMS_TLOG_PATH
The location of IMS DB transaction logging files. The default is the Enterprise Server system directory.
Note: Once created, you can move log files, but do not rename them. Before attempting to recover a database, all log files must reside in the directory specified by ES_IMS_TLOG_PATH.
ES_IMS_TLOG_COMPRESS
When set to 0 (zero), disables compression of the Backward Recovery TLOG file. When not compressed, the file contains only the information required to recover databases. The default is enabled.
Note: When enabled, Enterprise Server reclaims space in the file when information becomes obsolete.
ES_IMS_TLOG_FLUSH
When set to 1, forces the frequent flushing of TLOG and database buffers to disk.
Warning: Depending upon the number of database updates, the frequency of commits, and other computer activity, use of ES_IMS_TLOG_FLUSH could result in significant performance degradation.
Note: This environment variable is deprecated. Use ES_IMS_DB_TLOG_WRITETHRU to flush TLOG buffers and ES_IMS_DB_COMMIT_FLUSH to flush database buffers.
ES_IMS_TLOG_MAXSIZE
Maximum size of the IMS DB transaction logging file in bytes. The default is 4GB or h"FFF00000".
ES_IMS_TLOG_THRESHOLD
Threshold size of the IMS DB transaction logging file. When reached, the current TLOG file is closed and a new TLOG file created for subsequent transactions. The default is 2GB or h"7FFFFFFF".

TLOG File(s) used to Recover Databases

The actual TLOG file or files used to recover an IMS database depends on whether or not Forward recovery is enabled or disabled.

Forward Recovery Enabled
For both Forward and Backward recovery, use the most recent Forward recovery TLOG file.
Note: TLOG files created when Forward Recovery is enabled are not backed up because they are never overwritten.
Forward Recovery Disabled
For Backward recovery, use the default log file, IMSDB.TLOG, which is always backed up before a new one is created.

TLOG Naming Convention

With the exception of the IMSDB.TLOG file created and used when Forward recovery is disabled, Enterprise Server generates and renames TLOG files using this naming convention:

serverName-yymmddhhiisscc.TLOG

Where serverName is the name of the server on which the database is stored, and yymmddhhiisscc represents two digits for each: year, month, day, hour, minute, second, and microsecond.

Depending on the size of the database and the volume of transactions, recovery log files can become quite large. To better manage large-volume logs, Enterprise Server occasionally creates extension logs. The name of an extension log file is the same as the originating log file, plus an appended extension number such as 001, 002, etc.

During a recovery process, Enterprise Server uses log file time stamps to determine which log file or files are required for the restoration, and excludes out-of-date log files from the recovery. This minimizes the time required to complete the recovery.

Parent topic: IMS Database Recovery
Related concepts
Automatic Backward Recovery Process
Related reference
IMS-Specific Environment Variables


Rebuild Utility

When a database file has become corrupt and cannot be recovered by any other means, you must rebuild it. This situation is rare, but can occur if, for example, the file was open during a system crash.

To rebuild a corrupted database, use the Rebuild utility. You can execute Rebuild from the command line or from JCL. For complete documentation on using the Rebuild utility from the command line, see Rebuild.

To execute the Rebuild utility from JCL submission using MFDBUJCL:

  • The SYSIN data can specify a fully qualified database file or just the database file name.
  • Specify REBUILD as the parameter.
  • Use SYSIN data to name the file to be rebuilt and, optionally, an output file.

    With these files, the file extension, .DAT may be specified or not. If not specified, it is automatically appended.

  • The OUTPUT file is optional. If it is not included, then the database file is rebuilt in place.

    If you specify an OUTPUT file, then it becomes the rebuilt file and the INPUT file remains unchanged. In this situation, you must make sure that this output file is renamed to the original file name before it can be used.

Note:
  • If a database file requires a rebuild, then you should consider whether any associated index files should be rebuilt as well.
  • Make sure that there is enough free space on disk before submitting the rebuild job.

    You will need as much space as the file to be rebuilt requires, and if you have specified an OUTPUT file to be created in the same directory, then you need to account for the extra space requirement.

Parent topic: IMS Database Recovery


IMS Batch Backout

The Batch Backout utility allows database changes made by IMS batch applications (DLI and DBB) to be recovered either to a point prior to the start of the application or to a checkpoint.

Note:
  • Batch Backout is available only for offline batch IMS programs that access non-shared IMS databases. Batch IMS programs, both DLI and DBB, can only update IMS databases that are taken offline and made unavailable to online systems such as BMP programs, IMS transactions, CICS transactions and ODBA applications.
  • The Batch Backout utility can only be used for recovery of updates performed to offline IMS databases.
  • Batch Backout Implementation
  • Enabling Batch Backout Logging
  • Recovering Database Changes with the Batch Backout Utility
  • Restrictions and Limitations
  • Error Conditions
Parent topic: IMS Database Recovery


Batch Backout Implementation

To use the Batch Backout utility, you configure your IMS database update process to create batch backout log files. The Batch Backout process uses these log file to reverse changes. You can use the checkpoints that your applications set in these log files to back out selected changes only.

The Enterprise Server Batch Backout utility is similar in functionality to the IBM IMS batch backout implementation. The Enterprise Server implementation differs in the following ways:

  • The names of utilities, such as the backout program must not correspond to any names of similar utilities on the mainframe.
  • The format of the log files used as part of the database recovery process in the Enterprise Server implementation differs and is not compatible with the log files that are produced on the mainframe.
Note: Online IMS databases implemented in an Enterprise Server environment include dynamic (automatic) backout functionality. That is, when an application that has updated an online Enterprise Server environment IMS database abends, the uncommitted unit-of-work is backed out automatically, and does not require use of the Batch Backout utility. As a result, the features of Batch Backout that relate to the recovery of online databases are not needed and therefore unsupported in Enterprise Server.
Parent topic: IMS Batch Backout


Enabling Batch Backout Logging

Batch Backout logging for a batch IMS program is enabled in JCL by the presence of the BBOLOG DD statement. For example:

//BBOLOG  DD DSN=HLQ.PRJ01.BBOLOG.DEMO001T,DISP=(NEW,CATLG,DELETE)

IEFRDER and IEFRDER2 DD statements are ignored to avoid confusion with mainframe IMS logging and log record formats.

When enabled, updates to all IMS databases, along with checkpoint calls issued by the application program, are written to the BBOLOG dataset. Backup log files are extended as required in the event that they exceed size restrictions.

Standard JCL DSN management can be used for tracking these log datasets in the Enterprise Server catalog.

CAUTION:
When logging is enabled, the primary log file and any extensions must not exist. If the job detects that the primary or extended log file already exists, then the job terminates with an appropriate error message.

Below is sample batch JCL that specifies a BBOLOG dataset:

//IMSBATCH JOB 'MICRO FOCUS',CLASS=A,MSGCLASS=A
//* DLI PROGRAM EXECUTION
//*
//S01       EXEC PGM=DFSRRC00,REGION=4M,
//          PARM='BMP,DEMO001B,DEMO001T,,,,,,,,,CDLI,,N,N'
//REPORT1   DD  SYSOUT=*
//BTSLST    DD  SYSOUT=*
//IMSERR    DD  SYSOUT=*
//IEFRDER   DD  DUMMY
//BBOLOG    DD  DSN=HLQ.PRJ01.BBOLOG.DEMO001T,DISP=(NEW,CATLG,DELETE)
//PRINTDD   DD  SYSOUT=*
//SYSOUT    DD  SYSOUT=*
//SYSPRINT  DD  SYSOUT=*
//
Parent topic: IMS Batch Backout


Recovering Database Changes with the Batch Backout Utility

The Batch Backout utility processes a backout log file and removes the updates to the IMS databases that were issued from the program that created the log file. The log file is processed in reverse. Database updates can be rolled back either for the entire batch job or back to a specific checkpoint ID.

The input log file to the Batch Backout utility is specified on the BBOLOGI DD statement. The log file must be catalogued in Enterprise Server as follows:

//BBOLOGI DD DSN=HLQ.PRJ01.BBOLOG.DEMO001T,DISP=SHR

You can specify an optional recovery log file using the BBOLOGO DD statement. It too must be catalogued in Enterprise Server, for example:

//BBOLOGO DD DSN=HLQ.PRJ01.BBOLOG.RECOVERY,DISP=(NEW,CATLG,DELETE)

You can use this log output file in the event that the database file needs to be restored to its state before the backout utility was run. In this event, use this recovery log as the input log (BBOLOGI) to a subsequent run of the backout utility.

CAUTION:
it is important to be aware of the existence of the extension logs when backing up the logs or moving them to alternate locations. The recovery log to be created (that is the file associated with ddname BBOLOGO) data file and any extensions associated with it must not exist. In this event, the recovery job terminates with the appropriate error message.
  • Using Checkpoints with Batch Backout
  • Using Extended Log Files
  • Batch Backout Example JCL
Parent topic: IMS Batch Backout


Using Checkpoints with Batch Backout

Database updates can be rolled back either for the entire batch job or back to a specific checkpoint ID. The backout functionality is implemented in the MFDBUJCL IMS Database Utility JCL interface. You specify PARM='BBO' to activate batch backout. For example:

//BACKOUT EXEC PGM=MFDBUJCL,PARM='BBO'

If restarting from a checkpoint, the checkpoint ID is specified in the SYSIN DD, for example:

  //SYSIN   DD *
  CHKPT CHECK001
  /*

Checkpoint options are listed in the table below.

CHKPT Keyword | Behavior
LAST | Default. Restores to the point of the last successful checkpoint call.
ALL | Backs out all checkpoints.
checkpoint id | Restores to the checkpoint specified. This id is limited to eight characters.
Parent topic: Recovering Database Changes with the Batch Backout Utility


Using Extended Log Files

When database logging is enabled, it is possible that the log file can become so large that it is necessary to create one or more extended log files. In this event, the extended log file or files are created in the same directory as the primary log file. These files are not catalogued with Enterprise Server.

The naming convention for extended logs is that an underscore and a sequential numeric value is added to the end of the name of the primary log file. For example, if the primary log file is named BankDemoLog.dat, then the extended log files are named BankDemoLog.dat_1, BankDemoLog.dat_2, . . . BankDemoLog.dat_nn, . . .

CAUTION:
When a database batch job is submitted and logging is enabled, the primary log file and its extensions must not exist. If the job detects that the primary or extended log file already exists, then the job terminates with an appropriate error message. Similarly for the batch backout utility, if you want the optional recovery log to be created (that is the file associated with ddname BBOLOGO) , then that recovery data file and any extensions associated with it must not exist.

Consequently, it is important to be aware of the existence of the extension logs when backing up the logs or moving them to alternate locations.

Parent topic: Recovering Database Changes with the Batch Backout Utility


Batch Backout Example JCL

Below is sample JCL that invokes the backout process . In the example code:

  • The process uses the HLQ.PRJ01.BBOLOG.DEMO001T log file.
  • The backout process starts from the end of the log file, and backs out to the checkpoint CHECKOO1
  • The process creates the output log file: BBOLOG.BBOLOG2
//BBO    JOB 'IMSDBU BATCH BACKOUT',CLASS=A,MSGCLASS=A
//*
//* THIS JOB DEMONSTRATES THE BATCH BACKOUT UTILITY
//*
//BACKOUT EXEC PGM=MFDBUJCL,PARM='BBO'
//SYSOUT  DD SYSOUT=*
//SYSIN   DD *
CHKPT CHECK001
/*
//BBOLOGI DD DSN=HLQ.PRJ01.BBOLOG.DEMO001T,DISP=SHR
//BBOLOGO DD DSN=HLQ.PRJ01.BBOLOG.BBOLOG2,DISP=(NEW,CATLG,DELETE)
Parent topic: Recovering Database Changes with the Batch Backout Utility


Restrictions and Limitations

Batch Backout is not supported for the following cases:

  • BMP programs: BMP programs participate with online shared IMS databases and are not eligible for backout processing.
  • GSAM databases are not supported for batch backout.
  • Databases which have been made available to online BMP programs, IMS transactions, CICS transactions or ODBA applications are no longer eligible for batch backout processing.
  • Batch Backout processing is currently limited to a single input log file. DD concatenation or multiple input DD statements are not supported. If there are multiple input log files, then you need to run the backout utility multiple times. Take care to process the files in the correct order.
  • Recovery after a crash in the Enterprise Server database engine may not be possible without external intervention.
Parent topic: IMS Batch Backout


Error Conditions

If the backout fails due to an error, the job returns an error condition of 20, and the database file is unchanged.

A return code of zero indicates success.

If an error occurs, then the following messages can be displayed in the job log. Use these messages to assist in problem determination and correction.

Message | Description
MFDBUJCL: PROBLEM WITH THE INPUT BACKOUT LOG | The input backout log may be corrupt or unreadable.
MFDBUJCL: PROBLEM WITH THE OUTPUT RECOVERY LOG. | In this event, the physical name of the recovery log file is displayed.
MFDBUJCL: PROBLEM WITH THE FILE TO BE RECOVERED | The physical name of the database file is displayed. If the file has been determined to be corrupt, then the error message indicates this as well as instructions for rebuilding the data file.
MFDBUJCL: ILLEGAL CONFIGURATION ITEM | This is an internal message.
MFDBUJCL: CHECKPOINT SET BUT NOT FOUND | A checkpoint was supplied in the SYSIN data but was not found in the log file.
MFDBUJCL: BACKOUT SUCCESSFUL. HOWEVER THE RECOVERY DATASET SHOULD NOT BE TRUSTED TO RUN A RECOVERY | This is a warning message. The backout of the dataset was complete, but the recovery log may be invalid and should not be used in a recovery of the dataset.

Additionally, the job log may display reason codes, files status codes or other messages which may help in problem determination.

Parent topic: IMS Batch Backout


Enterprise Server warm/cold start

The following applies to warm and cold starts of the Enterprise Server IMS Database Control feature.

  • All database statuses are set to NOTOPEN when an enterprise server is first started and when a cold start is performed.
  • When IMS Database Control is started via a warm restart, either by an automatic restart after the abnormal termination of Database Control or by a normal startup, database statuses are restored.
  • If a warm start is the result of Database Control termination and the databases have been left in an ambiguous state, they are recovered by the Backward Recovery process.
  • If a warm start is the result of Database Control termination and the databases are not recoverable, then they might be placed in a stopped state.
Parent topic: IMS Database Recovery


IMS Checkpoints

The following topics describe the IMS checkpoint functionality available in Enterprise Server:

  • Basic and Symbolic Checkpoint Calls
  • IMSLGR Files
  • Avoiding Dataset Contention
Parent topic: IMS Database Administration


Basic and Symbolic Checkpoint Calls

Enterprise Server supports basic checkpoint (CHKP) calls, and symbolic checkpoint and Extended Restart (XSRT) calls.

Basic CHKP Calls

The basic CHKP call is available from message-driven transactions as well as BMPs and batch programs. Basic CHKP commits the changes your program has made to the database and establishes places in your program from which you can restart your program in the event that it terminates abnormally.

Symbolic CHKP and XSRT Calls

Symbolic CHKP and XSRT calls are only available to BMPs and batch programs.

The symbolic CHKP call commits the changes your program has made to the database and establishes places in your program from which you can restart your program in the event that it terminates abnormally. In addition, the CHKP call:

  • Works with the XRST call to restart your program if it terminates abnormally. An XRST call is required before a CHKP call to indicate to IMS that symbolic check points are being taken.
  • Designates a checkpoint ID, which is a place within the program from which you can restart it should the program terminate abnormally.
  • Designates up to seven data areas in your program to be automatically restored when your program is restarted after an abnormal termination.

The checkpoint ID and save areas are stored in files named IMSLOGR.DAT and IMSLOGR.IDX.

If an XRST call indicates that a restart should take place, the save areas are restored into the program's Working-Storage section. The restart checkpoint ID can be specified in the XRST call itself or as part of the Batch Program Command used to start the batch program. All XSRT calls, successful or not, are logged in the IMS System Log.

If an XSRT call indicates that a restart should take place, the save areas are restored into the program's Working-Storage. The restart checkpoint ID can be specified in the XRST call itself or as part of the Batch Program Command used to start the batch program. All restart calls, successful or not, are logged in the IMS System Log.

Note:
  • An XRST call does not reposition any databases, nor does it restore any PCB information.
  • CHKP and XSRT calls do not affect GSAM files and do not affect GSAM database position. GSAM updates are committed to the data file when the update call completes.
Parent topic: IMS Checkpoints


IMSLGR Files

The IMSLOGR files contain the save areas and checkpoint IDs for Symbolic Checkpoint (CHKP) calls. The IMSLOGR files are created the first time a CHKP call is made, and appended for each subsequent CHKP call. It is read when a Symbolic Restart call (XRST) is issued to restore the program save areas. You should delete these files periodically as they could grow quite large; however, once deleted, you cannot use XRST calls to restart from the deleted checkpoints.

These files are created in the Listing folder of your Enterprise Developer project.

Parent topic: IMS Checkpoints


Avoiding Dataset Contention

IMS programs that make use of checkpoint/restart, for example the Batch Backout functionality can use the IMSLOGR DD statement to define the input log file to use.

You can use this in the JCL to avoid dataset contention with other concurrent checkpoint/restart programs. This log file is used to store checkpoint IDs, GSAM reposition information and application save areas during extended checkpoint processing.

Parent topic: IMS Checkpoints


WebSphere MQ Support

This version of Enterprise Server supports both the MQ-IMS Bridge and IMS trigger monitoring.

Prerequisites

In addition to Enterprise Server, you must have WebSphere MQ client or server installed on your PC. To see supported WebSphere MQ versions, see the WebSphere MQ section in Additional Software Requirements.

  • MQ-IMS Bridge
    Describes the MQ-IMS Bridge feature used to communicate with WebSphere MQ and process requests on Enterprise Server.
  • IMS Trigger Monitoring
    Describes Enterprise Server support for IMS Trigger Monitoring.
Parent topic: IMS Support


MQ-IMS Bridge

The MQ-IMS Bridge feature enables you to capture incoming IMS transaction requests sent by an application to a WebSphere MQ queue, process those transactions on an enterprise server instance running an IMS application, and return output to the originating application via a WebSphere MQ output queue. When using an MQ listener with the MQ-IMS Bridge, this procedure requires no modifications to either the originating application or the IMS application.

Communications between Enterprise Server and WebSphere MQ are established by enabling MQ listener support and defining and enabling one or more MQ listeners in Enterprise Server.

An MQ listener is an Enterprise Server component that monitors messages sent to a specific WebSphere MQ queue. You can define an MQ listener to monitor either an input queue or an initiation queue. If you define the listener to monitor an initiation queue, Enterprise Server dynamically creates a listener for each associated input queue that receives inbound messages.

An MQ writer is an Enterprise Server component that sends messages back to a WebSphere MQ output queue. You do not define MQ writers. Enterprise Server creates them dynamically as needed.

The naming convention for all dynamically created listeners and writers is:

z#nnnnnn

nnnnnn is set initially to 000001, and is incremented by 1 with the creation of each subsequent listener or writer.

  • WebSphere MQ Configuration
    Describes the WebSphere MQ configuration requirements necessary to enable Enterprise Server to process MQ messages.
  • Enterprise Server Configuration
    Describes the Enterprise Server configuration requirements necessary to enable communication with WebSphere MQ.
  • MQ Listeners and Writers in ESMAC
    Describes what you can view and how you can modify MQ listeners and writers in ESMAC.
Parent topic: WebSphere MQ Support


WebSphere MQ Configuration

To use Enterprise Server MQ listeners and writers, you must configure WebSphere MQ Queue Manager to include an input queue and an output queue, and optionally an initiation queue:

Input Queue
This queue receives IMS transaction requests from your originating application.
Output Queue
This queue receives messages from the IMS application running on Enterprise Server.
Initiation Queue (optional)
If your queue manager in WebSphere MQ has a defined initiation queue, WebSphere MQ notifies that initiation queue when a message arrives at an input queue defined for the same queue manager. If you create your MQ listener in Enterprise Server to listen to an initiation queue rather than an input queue, Enterprise Server dynamically creates a listener for each input queue that receives a message. This can provide an advantage if your IMS application running on Enterprise Server is required to process messages from multiple input queues.

For complete information on creating and configuring MQ queues, see your IBM WebSphere MQ documentation.

Parent topic: MQ-IMS Bridge


Enterprise Server Configuration

To use Enterprise Server with the MQ-IMS Bridge, you must configure the following in an IMS-enabled enterprise server instance:

  1. Enable MQ listener support in Enterprise Server Administration.
  2. Create and enable an MQ listener for a WebSphere MQ queue.
Parent topic: MQ-IMS Bridge


MQ Listeners and Writers in ESMAC

With MQ listener support enabled, you can do the following in ESMAC with regard to MQ listeners and writers:

  • Monitor listener and writer activity
  • Start and stop listeners
  • Delete listeners and writers
  • Write dump information to the casdump.rec file
Parent topic: MQ-IMS Bridge


IMS Trigger Monitoring

Enterprise Server provides functionality for WebSphere MQ Trigger Monitoring for IMS, allowing IMS MPP programs to be scheduled when WebSphere MQ messages arrive on a designated WebSphere MQ queue.

Depending on your user granted permissions, you can do all or some of the following:

  • Start and stop the trigger monitor
  • Generate the PSB for the trigger monitor
  • Create the required XA resource

To enable trigger monitoring, IBM WebSphere MQ Server or IBM WebSphere MQ Client must be installed on the machine where Enterprise Server is running.

WebSphere MQ objects required for triggering must be defined. These are:
  • An application queue with the trigger control set on, a recommended trigger type of 'First'. The application queue will reference the process and initiation queue.
  • A process definition with the application type set to an integer value of 3 and an application id set to the IMS MPP transaction to be started. (The integer value of 3 for the application type is the numeric designation for IMS and ensures compatibility with WebSphere MQ UNIX installations.)
  • An initiation queue
The objects need to be defined from the WebSphere MQ command line or IDE. See IBM WebSphere MQ Queue Parameters documentation for details on how to do this.
  • Configuring Enterprise Server for WebSphere MQ Trigger Monitors
  • Security
  • Terminating an IMS Trigger Monitor Listener
Parent topic: WebSphere MQ Support


Configuring Enterprise Server for WebSphere MQ Trigger Monitors

The Enterprise Server region must be configured for both IMS and JES. For JES, you must define a batch initiator to process “class A” jobs. You need to ensure that enough initiators are defined for the job class to run all instances of the trigger monitor plus any other submitted jobs that will run under that class.

You also need to generate a PSB for the trigger monitor and create an XA resource to allow MPP applications to interface with IBM WebSphere MQ. A sample PSB definition file, csq4trmn.psb is included in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src folder.

The path to any IMS MPP transactions that are started by the Trigger Monitor must be present on the IMS TM Application Path.

In addition, you must also:
  • Enable MQ listener support in Enterprise Server Administration
  • Define an MQ listener to monitor the appropriate initiation queue
Parent topic: IMS Trigger Monitoring
Related tasks
To define a batch initiator or printer SEP


Security

If security is enabled, the trigger monitor will run under the userid that submitted the JCL to start the trigger monitor.

Parent topic: IMS Trigger Monitoring


Terminating an IMS Trigger Monitor Listener

Trigger monitor listeners are automatically terminated when the enterprise server instance is stopped. However, you can also force termination of a trigger monitor listener using any of these methods:

  • Use the casout /o command.
  • Use a program to place the CSQ4TRMN:STOP message on the WebSphere MQ initiation queue that the trigger monitor monitors.
  • Submit CSQ4STOP.JCL using the JCL Control Page in ESMAC. CSQ4STOP.JCL is located by detault in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src .
  • Use an IBM-supplied utility such as amqsput or amqsputc.
Parent topic: IMS Trigger Monitoring


Using Fileshare with Enterprise Server

Fileshare can be configured a number of ways to run within an Enterprise Server region:

  • iFileshare
    iFileshare (integrated Fileshare) is the version of Fileshare integrated with Enterprise Server, providing key aspects such as transactional support for CICS applications, and high availability for your VSAM datasets, as well as all the other features that come with Enterprise Server. We recommend that this configuration replaces existing configurations for Fileshare running under Enterprise Server.
  • Stand-alone Fileshare
    Stand-alone Fileshare is a configuration within Enterprise Server that enables you to direct all I/O for CICS- or JCL-related files to a stand-alone Fileshare server, providing transactional VSAM file access for CICS-related files.
Parent topic: MSS Configuration and Administration


iFileshare

Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.

Fileshare support running under Enterprise Server is provided using iFileshare (integrated Fileshare). You can configure iFileshare in its own Enterprise Server region, or you can add the capability to an existing Enterprise Server region. This configuration should replace your stand-alone Fileshare configuration.

A more robust configuration than an iFileshare server running in single mode is one running in a high availability group. A high availability group consists of a primary iFileshare server and one or more standby servers. Data files within the primary iFileshare server are replicated to all standby servers. In the event of your primary server failing, you have an up-to-date copy (minus any in-flight transactions) of your data files, and so one of the standby servers can assume the role of primary server; this process can occur automatically, or be performed manually.

Using these new Fileshare configurations, instead of a standalone Fileshare configuration, gives you the following benefits:

Control
Control and monitoring of the iFileshare process is driven through ESMAC, which centralizes the control of the Fileshare process within Enterprise Server Administration.
Performance
Scheduling of work for iFileshare is handled by Enterprise Server rather than relying on the network protocol scheduling that a standalone Fileshare uses; the benefit is a more scalable solution that is able to cope with heavier loads more efficiently.
Security
User authentication at log-on is handled by Enterprise Server-provided security, and not Fileshare's own security modules.
Recoverability
Using iFileshare opens up the opportunity to use Micro Focus' High Availability configuration, which provides failover support for files critical to your application.
  • iFileshare Restrictions
    There are a number of restrictions in place when using iFileshare.
  • iFileshare Configuration
    Configuration of an iFileshare server, either in single-user mode or high availability mode, is different to the traditional Fileshare configuration.
  • iFileshare Environment Variables
    An iFileshare server uses a number of environment variables for configuration.
Parent topic: Using Fileshare with Enterprise Server


iFileshare Restrictions

Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.

The following list contains the restrictions in place for iFileshare:

  • To use iFileshare, advanced logging must be enabled; you cannot use basic Fileshare logging.
  • The database reference file (dbase.ref) is only available for the purposes of the advanced recovery logging.
  • You cannot use a Fileshare server configuration file (FS.cfg) with iFileshare.
  • A high availability group must not contain a mixture of 32-bit and 64-bit servers; they must all be the same bitism.
  • A server failure within a high availability group requires manual intervention, and a restart of the group, before it can be added back into the group.
  • FSVIEW functions support is limited to the following commands:
    • Server Get
    • Status Get
    • Users Get
    • Files Get
    • Trace Toggle
    • File Get-Users
    • File Get-Locks
    • User Get-Files
  • Tracing can only be enabled using the command line FSVIEW function or through iFSVIEW (trace toggle).
Parent topic: iFileshare


iFileshare Configuration

Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.

Traditionally, the configuration of a standalone fileshare environment consisted of the fileshare server configuration, the client configuration, and a database reference file.

With iFileshare, the use of a configuration file for the server configuration is no longer required; the majority of the configuration is now facilitated through Enterprise Server; for example, a fileshare listener specifies the name of the server and the communications protocol in use. Fileshare security and authentication is also provided by existing Enterprise Server functionality instead of using a password file.

For external fileshare clients, a configuration file (typically FHREDIR.cfg) is still required, and are additional options required for iFileshare configuration.

The database reference file (dbase.ref) is also still required, and must reside in the system directory of the fileshare hosting region.

All of these configurations are covered in greater length in the following sections.

  • Configuring iFileshare for Single Mode
    Configure a new region or edit an existing region to enable iFileshare to run in Single mode; single mode consists of one iFileshare server, with no standby servers.
  • Configuring iFileshare for High Availability
    Create a number of regions to form a high availability group. Data is replicated throughout the group to provide high availability to mission-critical files in the event of a failure.
  • Configuring iFileshare for CICS Applications
    Additional configuration is required in order to process the file I/O from your CICS applications through iFileshare.
  • iFileshare Security
    Security within iFileshare, either in single mode or working as a high availability group, is provided through the standard Enterprise Server facilities.
Parent topic: iFileshare
Related reference
Fileshare Client Configuration Options


Configuring iFileshare for Single Mode

Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.
The single mode configuration for iFileshare consists of one iFileshare server, with no standby servers. Configure an Enterprise Server region to use iFileshare in single mode using one of the following methods:
  • Create a SIT that has Fileshare enabled, then specify the SIT in the CICS tab in the Mainframe Subsystem Support section.

  • Use the environment variable to configure the server.

The region's system directory becomes the iFileshare default directory; I/O operations will be performed from this directory.

This configuration provides a Fileshare server accessible to regions within the Enterprise Server, by prefixing ES- before the region's name; for example, if the region is called FSsvr, the name by which to access it is ES-FSsvr. To access the iFileshare server from outside of the Enterprise Server, see Additional iFileshare Configuration.

  • Additional iFileshare Configuration
    The basic iFileshare configuration enables Fileshare access from within Enterprise Server. You can configure your iFileshare region further by enabling rollforward and rollback recovery, and exposing the region to users outside of the Enterprise Server.
Parent topic: iFileshare Configuration
Related reference
Configuring iFileshare for CICS Applications


Additional iFileshare Configuration

The basic iFileshare configuration enables Fileshare access from within Enterprise Server. You can configure your iFileshare region further by enabling rollforward and rollback recovery, and exposing the region to users outside of the Enterprise Server.

Enabling recovery options

iFileshare supports both rollback and rollforward recovery, but you must enable advanced recovery logging before the region is started.

To do so, create a database reference file, named dbase.ref, in the region's system directory; for example:

fs /d dbase.ref /ltf logtrans /ltt f

For files that you want to be able to restore using the rollback and rollforward recovery processes, run the following command for each file:

fs /d dbase.ref /f <file-name>

where <file-name> is the name of the data file that will use advanced recovery logging.

Important: If you enable advanced recovery logging for an iFileshare server, I/O operations for all files in that region are processed through the iFileshare server when it is running.

For iFileshare, the basic recovery logging is deprecated.

Enabling tracing

To enable tracing for an iFileshare server, you must use the FSVIEW command line utility; at the command prompt, type:

fsview<Enter>
server set <listener-name><Enter>
trace toggle<Enter>

You can confirm that tracing is set for the iFileshare server by then typing server get.

Exposing the server to external users

To expose the iFileshare server to users outside of the Enterprise Server, you must create a fileshare listener for the iFileshare server region; this must have a different name to the name of the region. You can then send your I/O operations via the iFileshare server using the $$<listener-name> syntax, or by creating a file handler redirection module configuration file (see Configuring Your Fileshare Client).

Tip: For SMEM (shared memory) protocols, additional configuration may be required; see Configure the Listener and Configure the Shared Memory Namespace for more details.

Parent topic: Configuring iFileshare for Single Mode
Related reference
Configuring Your Fileshare Client
Advanced Recovery Logging
Configure the Listener
Configure the Shared Memory Namespace


Configuring iFileshare for High Availability

Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.

You can configure iFileshare to offer enhanced availability for mission critical files by configuring a high availability group, consisting of a primary iFileshare server and a number of standby servers. Each server is a local or remote Enterprise Server region.

Files critical to your application can be replicated from a primary server to the standby servers. Should the primary server fail, you have up-to-date data (minus any in-flight transactions) available on the standby servers, and one of those can assume the role of primary server.

This failover process can occur automatically if the minimum number of servers within the group are present, which is three: one primary server, and two standby servers. If the group has fewer servers than this, you can perform a manual failover.

If other Enterprise Server work is hosted within the group, the setup must be consistent on each server, so that in the event of a failover, the non-Fileshare work can be continued on the new primary server.

  • Configuring Servers in a High Availability Group
  • Running a High Availability Group
  • The Failover Recovery Process
  • High Availability Group Walkthrough
Parent topic: iFileshare Configuration
Related reference
Configuring iFileshare for CICS Applications


Configuring Servers in a High Availability Group

To configure an iFileshare high availability group, you must:
  • Configure the files to be replicated within the group by enabling advanced recovery logging for the primary iFileshare server.
  • Configure a Fileshare listener for each server within the group. In order for the failover process to seamlessly switch to a standby server, the same name must be used for each listener.

  • Configure the ES_HA_VSAM environment variable for each server within the group. The same value for this variable must be used for each server within the group.

Other regions on your system that are not specified within the group are unaffected by these settings.

  • Configure the Files to be Replicated within the High Availability Group
  • Configure the Listener
  • Configure the High Availability Group Environment Variable
  • Configuring Remote Servers in a High Availability Group
Parent topic: Configuring iFileshare for High Availability


Configure the Files to be Replicated within the High Availability Group

Only files that are configured for advanced recovery logging are replicated between the servers within an iFileshare high availability group. To enable advanced recovery logging and create the database reference file, run the following command from the system directory of your primary server, before you start the region:

fs /d dbase.ref /ltf logtrans /ltt f

For files that you want to be replicated, run the following command for each file to replicate:

fs /d dbase.ref /f <file-name>

where <file-name> is the name of the data file to replicate.

Important: Before you start the high availability group, you must ensure that existing data files are in a consistent state across all servers in the group. This can be accomplished by copying the files from the primary server to each of the secondary servers.
Parent topic: Configuring Servers in a High Availability Group
Related reference
Database Reference File Maintenance
Related information
Configure the Listener
Configure the High Availability Group Environment Variable
Configuring Remote Servers in a High Availability Group


Configure the Listener

You must configure each server within the iFileshare high availability group to use a Fileshare listener.

To configure a listener, you need to set:

  • Name. This is the name of the Fileshare server.
    Note: The same name must be used for the listener on each server within the group.
  • Endpoint Protocol. This can be set to TCP or SMEM.
    Tip: For SMEM (shared memory) protocols, additional configuration may be required depending on who needs to access the iFileshare server; see Configure the Shared Memory Namespace for more details.
  • Endpoint Address. For the TCP protocol, leave this field as its default. For the SMEM protocol, this must be a unique name within the high availability group.
  • Supported Conversation Type: Fileshare.
  • Configuration Information. The synchronous option is optional. It can improve performance for environments that have a small number of clients performing lots of I/O; conversely, this option can degrade performance for environments that have lots of clients making simultaneous requests.

Parent topic: Configuring Servers in a High Availability Group
Related information
Configure the Files to be Replicated within the High Availability Group
Configure the High Availability Group Environment Variable
Configuring Remote Servers in a High Availability Group
Configure the Shared Memory Namespace


Configure the High Availability Group Environment Variable

You must configure each server within the iFileshare high availability group to use the same value for the ES_HA_VSAM environment variable.

ES_HA_VSAM=<status>;<APPLID1-info>[;<APPLID2-info>;<APPLID3-info>...]

Where:

<status>
The type of iFileshare configuration. Can be one of:
N
No iFileshare configuration enabled.
S
Single iFileshare mode enabled (that is, no High Availability options enabled).
Y
iFileshare (High Availablity) enabled.
T
iFileshare (High Availablity), with ISC tracing, enabled.
<APPLID1-info>
The details for the primary server in the iFileshare group. (Only applicable for status options Y and T.)
<region-name>,<host-name or protocol>,<ISC-port>,<mfds-port>
Where:
<region-name>
Name of the region.
<host-name or protocol>
The host-name or the protocol of the region.
If the protocol is TCP/IP, specify the host-name; that is, an IP address, localhost, or a server name (e.g. nwb-svr1). If the protocol is shared memory (Windows only), specify ccism.
<ISC-port>
The port on which to host the dynamically generated ISC listener for the region; this port must be free.
If ISC links have been manually configured, this entry is optional; omit the entry by either terminating the node configuration with a semicolon, or by omitting the text between commas. This option must be omitted if you are using shared memory.
<mfds-port>
The port on which MFDS is running for the region; this defaults to 86.
If ISC links have been manually configured and MFDS is running on the default port (86), this entry is optional; omit the entry by either terminating the node configuration with a semicolon, or by omitting the text between commas. If MFDS is not hosted on the default port, you should always specify it, even if you have manually configured the ISC links.
<APPLIDx-info>
The details for a standby server(s) in the iFileshare high availability group. (Only applicable for status options Y and T.)
Important: The order in which you specify the standby servers determines the order that they are promoted to primary server status in the event of an automatic failover.
<region-name>,<host-name>,<ISC-port>,<mfds-port>
Where:
<region-name>
Name of the region.
<host-name>
The host-name for the region.
<ISC-port>
As before.
<mfds-port>
As before.

Example:

The following variable value, which must be the same on each server specified within the group, creates an iFileshare group of one primary server: (Prim-1) and two standby servers (Stand-1 and Stand-2)

Parent topic: Configuring Servers in a High Availability Group
Related information
Configure the Files to be Replicated within the High Availability Group
Configure the Listener
Configuring Remote Servers in a High Availability Group


Configuring Remote Servers in a High Availability Group

If your high availability group includes one or more servers that are hosted on a remote machine, there is additional configuration that must be performed before the group is started. The MFCC configuration file (mf-client.dat), which determines where to locate a FIleshare server, only specifies the localhost by default: therefore, you must update it with the address and MFDS port number of any machines in the group that are remote to you. Without this change, the group will not be able to automatically fail over to a remote server.

Note: The mf-client.dat file is located in the bin directory of your product installation directory. We recommend that you take a copy of this file, update the copy, and use the MFC_CONFIG environment variable to point to the updated file.

In the following example, we have a group configured with a primary server on a UNIX machine (suse11v1ax), a standby server on a Windows machine (home-win7), and a second standby server on the same UNIX machine as the primary server (suse11v1ax).

In order to process I/O requests to the iFileshare server from the Windows machine or to fail over to the Windows machine from the UNIX machine, you must add the line mrpi://suse11v1ax:3444 to the mf-client.dat file on your Windows machine, as indicated in the screen shot. (If your group had servers on other machines, you would need to add those entries too.) These entries should be ordered with the primary server location first, the first standby server next, and so on; this order is determined by the order in which the servers are specified in the ES_HA_VSAM environment variable.

Once this configuration is complete, you should be able to process requests to the iFileshare server from the Windows machine. If the group failed over to the Windows machine (server BROWN, home-win7), then you would have needed to repeat a similar process on the UNIX machine (before the group was started), by updating the mf-client.dat file with the name of the Windows machine (that is mrpi://home-win7:86).

Parent topic: Configuring Servers in a High Availability Group
Related information
Configure the Files to be Replicated within the High Availability Group
Configure the Listener
Configure the High Availability Group Environment Variable


Running a High Availability Group

When you have configured the regions for each iFileshare server within the high availability group, you only need to start the regions (in any particular order) to kick off the replication process.

When all regions in the group are running, you can verify that the group is configured correctly by performing the following checks:
  • In the system directories of the standby servers, a number of files have been added; amongst those, look out for:
    • The database reference file (dbase.ref), previously configured on the primary server.
    • A logging file (logtrans.tlog), the size of which will grow as file are replicated between the group.
      Note: If you restart the group, you must first remove the logging file from the system directory of each server in the group.

  • On the Server Information page of each server, check that the correct role has been assigned. Anything other than the two statuses below most likely indicates an error.

  • On the ESMAC page, ensure iFileshare is selected in the Resources pane, click iFSView, then click server get.

    The status of the iFileshare server appears.

Parent topic: Configuring iFileshare for High Availability


The Failover Recovery Process

The concept of having a high availability group is to ensure that, in the event of a hardware or software failure of your primary server, service to your data is disrupted as little as possible. The failover process ensures that a standby server in the group assumes the role of primary server, and continues to provide access to your data.

The failover process can occur automatically or manually. Manual failover is only required when your group has fewer than three active servers in the group (that is, one primary server and two standby servers).

When automatic failover occurs, the next standby server (as determined by the order in which the servers are listed in the ES_HA_VSAM environment variable) is promoted to be primary server. At the point of reconnection, a 9/125 error is produced, and the new primary server rolls back any in-flight transactions.

As part of the recovery process, the primary server that failed is removed from the iFileshare group, and can only be re-added to the group when the group itself is restarted. This is also true if a standby server fails. If a server's removal leaves the group without a minimum number of servers, file replication will still occur within the group, but the automatic failover process is unavailable until the group is restarted with at least a minimum number of servers.

To ensure your client application can still continue processing when the recovery process completes, you must configure your Fileshare client to automatically reconnect once a connection has been lost; this functionality is only available if you have the following lines to the Fileshare client configuration file (fhredir.cfg):

/um
/ra <number-of-attempts>
/rd <delay-between-attempts>

If the new primary server is on a remote machine, you must also have configured your mf-client.dat configuration file to locate iFileshare on the new machine; see Configuring Remote Servers in a High Availability Group.

  • Run the Failover Process Manually
Parent topic: Configuring iFileshare for High Availability
Related reference
Configuring Remote Servers in a High Availability Group


Run the Failover Process Manually

  1. On the Enterprise Server Administration home page, click Details in the Status column of an active standby server.
    Note: Typically, this will be the only server left in the group, as automatic failover would usually occur with three or more servers.
  2. Click ES Monitor & Control.

    The Server Information page appears.

  3. In the Resources group, ensure iFileshare is selected, then click Control.

    The iFS Control page appears.

  4. Select Force Takeover, then click Enter.

    The following message appears:

    ***----------------------------------------------***
*** Confirm active request and press enter again ***
***----------------------------------------------***
  5. Select Confirm, then click Enter.

    The following message appears:

    ***--------------------------------***
*** Takeover as Primary requested  ***
***--------------------------------***
  6. To verify the process has completed successfully, click iFSView, then click server get.

    In Current Server Status, (Primary) should be displayed after the current server name.

  7. Click Home, then click Details in the Communications Processes column for the new primary server

    The fileshare listener should be in a Started state.

The new primary server is ready to accept requests.
Parent topic: The Failover Recovery Process


High Availability Group Walkthrough

On completion of this walkthrough for a high availability group using iFileshare, you will have:
  • Created a primary server and two standby servers that will form the high availability group.
  • Configured each server within the group to use iFileshare.
  • Verified that the group roles have been assigned correctly during startup.
  • Configured access to a data file, and then processed it through iFileshare, thus demonstrating the replication process.
  • Emulated a failover situation to demonstrate one of the standby servers taking over the role of primary server.
  1. Setting up the Environment
  2. Create the Primary Server
  3. Create the Standby Servers
  4. Create the iFileshare Listener
  5. Configure the Shared Memory Namespace
  6. Configure Advanced Logging
  7. Add Existing Files for Use in the Group
  8. Start the Group
  9. Verify the Group Status
  10. Run a Test Program to Verify Replication
  11. Emulate a Failover Situation
Parent topic: Configuring iFileshare for High Availability


Setting up the Environment

  1. Create a new directory on your hard drive: c:\HA.
  2. In the newly created directory, create the following sub-directories:
    • RED
    • GREEN
    • BLUE
  3. Copy any existing data files that you plan to use within the group to each of these directories.
    Note: For this tutorial, we are going to create a new data file; therefore, this step is only required if you plan to use the group beyond the scope of these instructions.
You are now ready to create the enterprise servers that will make up the high availability group.
Parent topic: High Availability Group Walkthrough
Next topic: Create the Primary Server


Create the Primary Server

  1. On the Enterprise Server Administration home page, click Add.

    Page 1 of the Add server wizard appears.

  2. In the Server Name field, type RED, then click Next.

    Page 2 of the Add server wizard appears.

  3. Ensure that Micro Focus Enterprise Server with Mainframe Subsystem Support is selected, then click Next.

    Page 3 of the Add server wizard appears.

  4. In the System Directory field, type c:\HA\RED; this is the path to the directory that you created in the previous steps.
  5. Select Show Local Console.
  6. Clear the Create TS3270 listener option.
  7. In the Configuration Information field, type the following:
    [ES-Environment]
ES_HA_VSAM=Y;RED,locahost,9045,86;GREEN,localhost,9046;BLUE,locahost,9047

    This assumes that you are running MFDS on the standard port number of 86. It is possible to configure your communications to use shared memory; see Configure the High Availability Group Environment Variable for full syntax options for this variable.

  8. Click Add.

    The primary server is created, and appears in the table on the Enterprise Server Administration home page.

You can now create the standby servers.
Parent topic: High Availability Group Walkthrough
Previous topic: Setting up the Environment
Next topic: Create the Standby Servers


Create the Standby Servers

  1. On the Enterprise Server Administration home page, click Add.

    Page 1 of the Add server wizard appears.

  2. In the Server Name field, type GREEN, then click Next.

    Page 2 of the Add server wizard appears.

  3. Ensure that Micro Focus Enterprise Server with Mainframe Subsystem Support is selected, then click Next.

    Page 3 of the Add server wizard appears.

  4. In the System Directory field, type c:\HA\GREEN.
  5. Clear the Create TS3270 listener option.
  6. In the Configuration Information field, type the following:
    [ES-Environment]
ES_HA_VSAM=Y;RED,locahost,9045,86;GREEN,localhost,9046;BLUE,locahost,9047

    See Configure the High Availability Group Environment Variable for full syntax options for this variable.

  7. Click Add.
  8. Repeat this process for another server named BLUE, specifying c:\HA\BLUE as the system directory.

    The standby servers are created, and appear in the table on the Enterprise Server Administration home page.

When all of the servers have been created, you must add the required listener to each server.
Parent topic: High Availability Group Walkthrough
Previous topic: Create the Primary Server
Next topic: Create the iFileshare Listener


Create the iFileshare Listener

  1. On the Enterprise Server Administration home page, in the row for the RED server, click Details in the Communications Processes column.

    A list of listeners appears.

  2. Click Add.

    The new listener details appear.

  3. In the Endpoint Protocol filed, click TCP and select SMEM from the drop-down list.
  4. In the Name field, type FS1.

    This is the name of the Fileshare server.

  5. In the Endpoint Address field, type FS1.
  6. In the Supported Conversation Type list, select Fileshare.
  7. Click Add.
  8. Click Home to return to the Enterprise Server Administration home page, then repeat the same process for the GREEN and BLUE servers.
    Note: Each Endpoint Address within the group must be unique; therefore, when configuring each standby server, give the Endpoint Address a unique value.
The next task is to configure a global namespace for the listener.
Parent topic: High Availability Group Walkthrough
Previous topic: Create the Standby Servers
Next topic: Configure the Shared Memory Namespace


Configure the Shared Memory Namespace

When a shared memory iFileshare listener is started, the listener endpoint uses a localised namespace (based on the user-name that started the iFileshare server).

Later in this tutorial, we start iFileshare from the Enterprise Server Administration page, and that by default starts with a user called mfuser. Without specifying that the endpoint uses a global namespace, user names other than mfuser would not be able to locate the listener, and thus unable to use the iFileshare server.

If you use the TCP/IP protocol, or only require the same user that starts the iFileshare server to process files through iFileshare, then you do not need to complete these steps.

  1. In your product installation's \bin directory, create a cci.ini file if one does not already exist.

    If one already exists in that location, update the following to it.

  2. Within the [ccismem-base] section, add the following option:
    [ccismem-base]
use_global_namespace=yes
  3. Save and close the file

    This will enable different user-names to interact with the iFileshare server.

The next task is to configure iFileshare for advanced logging.
Parent topic: High Availability Group Walkthrough
Previous topic: Create the iFileshare Listener
Next topic: Configure Advanced Logging


Configure Advanced Logging

  1. From an Enterprise Developer command prompt, navigate to the system directory of the primary server: c:\HA\RED.
  2. Type the following:
    fs /d dbase.ref /ltf logtrans /ltt f

    This enables advanced logging for the files that are going to be handled through iFileshare.

The next task is to add existing files to the dbase.ref file.
Parent topic: High Availability Group Walkthrough
Previous topic: Configure the Shared Memory Namespace
Next topic: Add Existing Files for Use in the Group


Add Existing Files for Use in the Group

  1. From an Enterprise Developer command prompt, navigate to the system directory of the primary server: c:\HA\RED.
  2. Type the following:
    fs /d dbase.ref /f FILE.DAT

    FILE.DAT is a file that will be used later in this tutorial to verify that the replication process is working correctly.

  3. If you copied any existing data files to your system directories during the Setting the Environment step, repeat the previous step, replacing FILE.DAT with the name of each file you plan to use in the group.

The group is now ready to be started.

Parent topic: High Availability Group Walkthrough
Previous topic: Configure Advanced Logging
Next topic: Start the Group


Start the Group

  1. On the Enterprise Server Administration home page, click the Start button in the row of the RED server.

  2. Click OK to continue.

    The Enterprise Server Administration home page appears and the Enterprise Server Console Daemon window displays the progress of the start-up (RED server only); we will check this in further details later.

  3. Repeat these steps to start the remaining servers in the group
    Note: The order in which you start the servers is not important.
  4. On the Enterprise Server Administration home page, ensure that each server in the group is started.
Once all the server in the group have started, we need to check that they have been assigned the correct roles and are communicating as they should.
Parent topic: High Availability Group Walkthrough
Previous topic: Add Existing Files for Use in the Group
Next topic: Verify the Group Status


Verify the Group Status

There are a number of steps that you can perform, once the group is running, to show that the group is ready to use.
  1. Check the role assigned to each server:
    1. On the Enterprise Server Administration home page, click Details in the Status column of a server in the group.

      The Contol page appears.

    2. Click ES Monitor & Control.

      The Server Information page appears.

    3. Check that the server has the correct role assigned. Anything other than the two statuses below most likely indicates an error.

    4. Repeat these sub-steps for each server in the group.
  2. Check that the Fileshare listener is running on the primary server, but blocked on the standby servers:
    1. On the Enterprise Server Administration home page, click Details in the Communications Processes column of a server in the group.

      The list of listeners and their statuses appear.

    2. Check that the Fileshare listener is Started if it is the primary server, or Blocked if it is a standby server.

    3. Repeat these sub-steps for each server in the group.
  3. Check the status of the Fileshare server:
    1. On the Enterprise Server Administration home page, click Details in the Status column of the RED server.

      The Contol page appears.

    2. Click ES Monitor & Control.

      The Server Information page appears.

    3. In the Resources group, ensure iFileshare is selected, then click iFSView.

      The IFSView console appears.

    4. Click server get.

      Details of the server appear.

Parent topic: High Availability Group Walkthrough
Previous topic: Start the Group
Next topic: Run a Test Program to Verify Replication


Run a Test Program to Verify Replication

Once you have verified that the high availability group is configured correctly, run the following COBOL program to demonstrate that the replication process is working correctly within the group. This program creates a data file, the name of which was added to the dbase.ref file in an earlier step. When the program has finished, the data file (FILE.DAT) should have been created on the primary server (RED), then replicated to the standby servers (GREEN and BLUE).
  1. In the c:\HA directory, create a new file called runner.cbl, then paste the following code into it and save the file:
          $set callfh"FHREDIR"
       environment division.
       configuration section.
       input-output section.
       file-control.

           select optional idxfile
               assign to disk "file.dat"
               organization is indexed
               access is dynamic
               lock mode is automatic
               record key is idxfile-primary-key
               file status is file-status.

       data division.
       file section.

       fd  idxfile.
       01  idxfile-rec.
           03  idxfile-primary-key pic 999999999.

       working-storage section.
           01 file-status.
                05 status-key-1     pic x.
                05 status-key-2     pic x.
                05 binary-status redefines status-key-2  pic 99 comp-x.

       Procedure Division.
           open output idxfile
           move 0 to idxfile-primary-key
           perform 100 times
              perform 20 times
              add 1 to idxfile-primary-key
                  write idxfile-rec
              end-perform
              commit
           end-perform
           close idxfile
           stop run.
  2. From an Enterprise Developer command prompt, type:
    cobol runner.cbl int();

    The COBOL file is compiled to an .int file.

  3. In the same directory, create the FHREDIR.cfg file that is specified in the COBOL program, then paste the following options into it and save the file.
    /s FS1
/um
/ra 5
/rd 5000
/cm ccism
  4. Run the program by typing the following:
    run runner.int
    Tip: While the program is running, on the Enterprise Server Administration home page, for the primary server, click Details > ES Monitor & Control > iFSView > files get to show the open file within Fileshare.

  5. When the program has completed, check the system directory for each server: they should each contain FILE.DAT. This verifies that replication is working correctly within the group.
Parent topic: High Availability Group Walkthrough
Previous topic: Verify the Group Status
Next topic: Emulate a Failover Situation


Emulate a Failover Situation

To demonstrate what would happen if the primary server were to fail, you can kill off its process, which should initiate the failover process.

  1. On the Enterprise Server Administration home page, click Details in the Status column for the primary server.
  2. Click ES Monitor & Control.
  3. Click SEPs.

    The SEPs information appears.

  4. Make a note of the process ID for the ES Manager.
  5. On Windows, do the following:
    1. Press Ctrl+Shift+Esc.

      The Windows Task Manager appears.

    2. If not already on display, click the Processes tab.
    3. If the PID column is not displayed, right-click the Name column heading and select PID.

      The PID column appears.

    4. Highlight the entry for the PID noted in the previous step, then click End Task or End Process (depending on your version of Windows).
      Note: If you cannot locate the PID, click Show processes from all users.
    5. If you are prompted to confirm, click End Process again.

      This kills off the primary server and automatically assigns the role of primary to one of the standby servers.

    This kills off the primary server and automatically assigns the role of primary to one of the standby servers.
  6. On UNIX, type the following:
    kill <process ID>

    This kills off the primary server and automatically assigns the role of primary to one of the standby servers.

  7. On the Enterprise Server Administration home page, click Details in the Status column of each standby server, then click ES Monitor & Control. You will notice that one of the standby servers is now displaying a status of HA VSAM Primary.
  8. To confirm the group is still operating as expected, from the Enterprise Developer command prompt, type:
    run runner.int

    This reruns the previous program; if you examine the system directories for each of the remaining servers, you'll notice that the timestamp for FILE.DAT has been updated, confirming that the file is still being replicated within the group.

This concludes the walkthrough. You can now stop each server to close the group.
Note: If you plan to restart the group, ensure that you delete the logtrans.tlog file from the system directory on each server in the group before it is started.
Parent topic: High Availability Group Walkthrough
Previous topic: Run a Test Program to Verify Replication


Configuring iFileshare for CICS Applications

iFileshare, either in single mode or working as a high availability group, can be configured to work with your CICS regions in two ways: you can configure your CICS regions to connect to a server on a separate Enterprise server region, or you can configure the iFileshare to be in the same region as your CICS application.

To configure access to an external iFileshare server

To configure your CICS application to use files located on an external iFileshare server, you must configure the following:

  • Specify the Fileshare server in the FCT details for each file you require to access this way:

    Tip: If Start Open is selected, you can use the files get option from iFSView after the file is open to show that the configuration is correct: when you click files get, the file configured in the FCT should appear.
  • Next, you must edit the SIT to specify a valid CICS user, and ensure that the Integrated field is unchecked (this is used when iFileshare is part of the CICS region).

If the iFileshare server is already configured correctly, you should only have to start this region to complete the configuration.

To configure access to an iFileshare server that is part of the CICS region

To configure your CICS application to use files located on a iFileshare server that is also part of the same CICS region, you must ensure that the following details are set:

  • In the FCT details for each file you plan to use via iFileshare, ensure that one or both of the Backward Recovery or Forward Recovery options are selected.

  • Configure the ES_HA_VSAM environment variable in the normal manner; for example:

Important: If you have configured a high availability group, the CICS configuration for each server in the group must be identical, so that in the event of a failover, CICS processing can continue.
Parent topic: iFileshare Configuration
Related concepts
Configuring iFileshare for Single Mode
Configuring iFileshare for High Availability


iFileshare Security

Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.

Security within iFileshare, either in single mode or working as a high availability group, is provided through the standard Enterprise Server facilities.

Micro Focus recommends that you use an ESM (External Security Manager) to control access to the files within iFileshare.

Native Enterprise Server work running on the iFileshare primary server is authorized in the SEPs and no further security checking is done. For external clients (Enterprise Server SEPs or standalone processes), the user ID and password combination is validated at sign-on, and the ID is checked for authorization to access files on the iFileshare primary server. If you are not using an ESM, authorization is assumed when the user ID/password is validated; otherwise, the ESM controls user authorization.

The following is a sample ESM configuration:

# Sample security definitions for Integrated Fileshare

####################
# Default IFS User #
####################
dn: CN=IFSUSER,CN=Enterprise Server Users,CN=Micro Focus,CN=Program Data,DC=X
changetype: add
objectClass: microfocus-MFDS-User
microfocus-MFDS-UID: mfuid
microfocus-MFDS-User-MTO-Priority: 0
microfocus-MFDS-User-MTO-Timeout: 0
microfocus-MFDS-User-MTO-OperatorClass: 0
microfocus-MFDS-User-AllowLogon: TRUE
microfocus-MFDS-User-DefaultGroup: ALLUSER
description: Default IFS user

###################
# ES Class = SIFS #
###################
dn: CN=SIFS,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=X
changetype: add
objectClass: top
objectClass: container
description: Integrated Fileshare SIGNON

###############################
# Integrated Fileshare SIGNON #
###############################
dn: CN=ESDEMO,CN=SIFS,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=X
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: SIFS
microfocus-MFDS-Resource-ACE: allow:SYSADM group:execute
microfocus-MFDS-Resource-ACE: allow:ALLUSER group:execute
microfocus-MFDS-Resource-ACE: deny:*:execute
microfocus-MFDS-UID: mfuid
description: Give sysadmin, normal, and anonymous users access to IFS
Parent topic: iFileshare Configuration


iFileshare Environment Variables

Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.

The following environment variables are specific to using iFileshare.

Variable | Description
ES_HA_VSAM Determines if a region is configured as an iFileshare server. The possible values are:
N (No)
The region is not configured as an iFileshare server. This is the default.
S (Single)
The region is configured as an iFileshare server in single mode (that is, no High Availability options enabled).
Y (Yes)
The region is configured as an iFileshare (High Availability) server. Additional configuration is required when using this setting; see Configuring Servers in an High Availability Group.
T (Yes & ISC Tracing)
The region is configured as an iFileshare (High Availability) server, and also includes ISC tracing. Additional configuration is required when using this setting; see Configuring Servers in an High Availability Group.
ES_USR_DFLT_IFS | The default iFileshare user is IFSUSER; this is the user that is set when you start the iFileshare server region without specifying a user. Use this variable to set a different default user name (maximum 8 characters).
FSLOGCOMP | If your iFileshare server uses data compression, set FSLOGCOMP=Y to also compress the data in the transaction log files. Default is N.
Parent topic: iFileshare
Related reference
Configuring Servers in a High Availability Group


Stand-alone Fileshare

You can configure an enterprise server so that all I/O for CICS- or JCL-related files is handled by a stand-alone Fileshare server. The advantage of this setup is that it provides transactional VSAM file access for CICS-related files.

Use the following sections and tutorials to configure the Fileshare server, and configure the files you will access using Fileshare.

  • Overview
  • Starting a Fileshare Server
  • Stopping a Fileshare Server
  • Configuration
  • Walkthrough
Parent topic: Using Fileshare with Enterprise Server


Overview

Fileshare is a client/server file handler, supplied as part of Enterprise Server. When you configure an enterprise server to use Fileshare, you are making the enterprise server a Fileshare client, so that some or all file I/O requests coming from applications running in that enterprise server will be handled by a Fileshare server.

Fileshare can be used for CICS applications, files accessed by JCL, and even the catalog itself. It can also access data files on other systems running on the same network as the machine running Enterprise Server. These Fileshare files can still be accessed by other applications at the same time.

Although its name implies file sharing, the major benefit of Fileshare in Enterprise Server is when used with CICS, as it provides transactional access support to data files using the COMMIT and ROLLBACK verbs or EXEC CICS SYNCPOINT. Without using Fileshare, there is no CICS transactional behavior in Enterprise Server.

Fileshare also provides rollforward and rollback recovery to ensure the integrity of your files in the event of a system failure.

  • Transactional VSAM Access
Parent topic: Stand-alone Fileshare


Transactional VSAM Access

On an IBM mainframe, when a CICS application accesses a VSAM dataset, the access is transactional. This means that CICS, acting as a Transaction Manager (TM), ensures that the updates to the VSAM dataset are committed or rolled back as appropriate. The application can control the transaction boundaries with explicit EXEC CICS SYNCPOINT commands, and CICS implicitly controls the transaction at end of task.

In Mainframe Subsystem Support, CICS provides VSAM emulation but does not provide transactional access to these resources. Fileshare does provide such access. Mainframe Subsystem Support acts as the TM and uses Fileshare's Resource Manager (RM) to provide behavior compatible with mainframe CICS.

No changes to your program source are needed to take advantage of Fileshare. If a resource definition indicates that a resource uses Fileshare, the default configuration provides backward recovery for that resource. This means that if an application explicitly backs out updates to a VSAM dataset, or CICS rolls back an update because of an application failure, Fileshare ensures that the dataset is returned to a consistent state.

If a file is accessed only from JCL, not CICS, then there is no advantage in using Fileshare for it. However, if it is accessed by both, and you configure it to use Fileshare for the sake of transactional VSAM access, then Fileshare is used for all accesses to it, whether from CICS or JCL. Refer to Files Accessed by Both CICS and JCL for details on how to handle potential conflicts between accesses from CICS and JCL.

Parent topic: Overview
Related information
Files Accessed by Both CICS and JCL


Starting a Fileshare Server

You must run Fileshare commands from the Enterprise Developer command prompt.

To start a Fileshare server:

start fs /s server-name

where server-name names the server, and corresponds to the ID by which the client region knows the server. The /s parameter is mandatory on each Fileshare command unless you are using a configuration file. For a list of valid parameters, see the section Using a Fileshare Server Configuration File.

This command starts a server with the default protocol enabled, and with no password checking performed when a client tries to access the server. The default protocol is TCP/IP. You can use the /cm parameter to explicitly name the protocols to be used. For example:

start fs /s fstest /cm ccitc32 /cm ccism32

In this example, ccitc32 and ccism32 are the CCI modules required for TCP/IP and Shared Memory, respectively.

The following example starts a server with password checking applied through the file fs.pwd:

start fs /s fstest /cm ccitc32 /pf fs.pwd

Refer to Using a Fileshare Password File for details on how password checking works.

Parent topic: Stand-alone Fileshare
Related information
Stopping a Fileshare Server
Fileshare Options


Stopping a Fileshare Server

Before stopping a Fileshare Server, you must either stop all enterprise servers connected to it or make sure that all the files held on Fileshare servers are closed.

To stop a Fileshare server locally, go to the session from which you started it, and press the Esc key: you see the prompt:

FS097-I Are you sure you wish to close the Fileshare Server? (Y/N)

Press Y to continue the shutdown; enter any other key to let the server continue running.

If any database files are open when you reply Y, a second prompt appears:

FS111-I Warning - database files are still open
    Continue with the close (Y/N)?

If you enter Y, Fileshare closes all open files and shuts down. Enter any other key to cancel the shutdown.

Parent topic: Stand-alone Fileshare
Related information
Starting a Fileshare Server


Configuration

You need to configure both the enterprise server (that is, the Fileshare client) and the Fileshare server:

  • Fileshare Server Configuration
  • Fileshare Client Configuration
Parent topic: Stand-alone Fileshare


Fileshare Server Configuration

  • Using a Fileshare Configuration File
    You can specify your Fileshare parameters in a configuration file, as an alternative to specifying them on the command line. A Fileshare Server configuration file is an ASCII text file that contains one option per line.
  • Fileshare Options
    The options available to configure the Fileshare server can be entered on the command line or contained within a configuration file.
  • Using a Fileshare Password File
    Specifying a password file when you start a Fileshare server enables you to restrict unauthorized access to files.
  • Monitoring Fileshare Activity
    You can monitor the activity on a Fileshare server by pressing F2 from the same session in which you started the server. This turns on Fileshare's trace facility.
  • FSView
    FSView is a command-line utility for administering Fileshare servers. Some commands that control a Fileshare server cannot be entered at the Fileshare console window; these commands must be entered through FSView instead.
  • Installing Fileshare as a Service
    You can install Fileshare as a Windows service, which allows you to start and stop the server from the Windows Control Panel.
  • Optimizing the Fileshare Server
    There are a number of changes you can make to your Fileshare server to make it run faster.
Parent topic: Configuration


Using a Fileshare Configuration File

You can specify your Fileshare parameters in a configuration file, as an alternative to specifying them on the command line. A Fileshare Server configuration file is an ASCII text file that contains one option per line.

If you give no parameters on the command line, then fs looks for a configuration file. By default, it looks for a file called fs.cfg in the Fileshare directory, that is, the directory where you started fs. You can use the /cf parameter to specify a different path and/or filename.

For example, you could have a configuration file c:\fsdir\fsconf.cfg containing:

/s server1
/tr f

and start your server server1, from your application command prompt, by entering:

fs /cf fsconf.cfg

Another example is that you could have a configuration file c:\fsdir\fs.cfg containing:

/s server1

and start your server by entering:

fs
Parent topic: Fileshare Server Configuration
Related information
Fileshare Options
Using a Fileshare Password File
Monitoring Fileshare Activity
FSView
Installing Fileshare as a Service
Optimizing the Fileshare Server
Starting a Fileshare Server


Fileshare Options

The Fileshare Server configuration file, fs.cfg, contains the Fileshare configuration options described below. Only the /s option is required. The /pf option is strongly recommended, however, as without it you cannot enforce any Fileshare security, although MSS does provide Resource Security Level (RSL) checking.

/s server-name

Specifies that server-name is the name that the Fileshare Server registers on the network. The name specified has to be unique to that Fileshare Server and must correspond to the Fileshare Server ID specified in the enterprise server's Resource Definition Tables. If a Fileshare Server with that name is already registered on the network, an error is returned.

[/d database-reference-file]

Specifies database-reference-file as the name of the database reference file that the Fileshare Server is to use.

/t nnnnnnnn

Sets the transaction processing timeout, in seconds. If the server does not hear from its client in this period, and another client has requested access to records locked as part of the transaction, all files involved in the transaction are rolled back to their original state and all locks are removed.

The default timeout is 60 seconds. You can disable timeout by setting this to 0. The valid values are 0 through 99999999.

[/m record-size]

Specifies the maximum record size that the Fileshare Server processes in kilobytes. The valid values for record-size are 16 through 64. If you specify a value less than 16, the Fileshare Server uses a maximum record size of 16KB. If you specify a value greater than 64, the Fileshare Server uses a maximum record size of 64KB. if you do not include this option, the Fileshare Server uses a maximum record size of 64KB. Setting a lower value than the default value reduces the amount of memory that the Fileshare Server needs to run.

/cm cci-protocol

Specifies cci-protocol as one of the CCI communications protocols that the Fileshare Server can use to receive communications from a Fileshare Client. Repeat this option for every communications protocol that you want to use to contact this Fileshare Server. Valid values for cci-protocol are:

  • CCITC32 for TCP/IP
  • CCISM32 for Shared Memory

If you do not specify any entries, the default is CCITC32.

[/cf configuration-file]

Specifies the name of the Fileshare Server configuration file. Use this option only on the command line. When using this option, you must specify the required Fileshare Server options in the configuration file. If you do not specify a name for the configuration file, it defaults to fs.cfg in the Fileshare Server's current directory.

/pf password-file

Names the password file used by this server. This option activates the Fileshare Password system. If you do not use this option, the Fileshare Server runs without security enabled.

[/tr f]

Specifies that the Fileshare Server trace option is activated as soon as the Fileshare Server starts. The trace echoes to the screen and a file called fsscreen.lst in the Fileshare Server's current directory. This option seriously impacts the Fileshare Server's performance. Use it only 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.

Examples

Assume the file fs.cfg contains the following lines:

/s fsserv1
/cm ccitc32
/cm ccism32

/pf serv1.pwd

If you enter the command:

fs

Fileshare reads fs.cfg and starts a server named FSSERV1, with the TCP/IP and Shared Memory protocols enabled. It uses the file serv1.pwd for password security.

Parent topic: Fileshare Server Configuration
Related information
Using a Fileshare Configuration File
Using a Fileshare Password File
Monitoring Fileshare Activity
FSView
Installing Fileshare as a Service
Optimizing the Fileshare Server


Using a Fileshare Password File

A Fileshare Server uses its password file to verify that a client enterprise server is entitled to access its files. Although Fileshare can run without a password file, you must use one if you want to apply any security through the Fileshare Server itself. This is strongly recommended, since Fileshare has access to all the files on your system.

The Fileshare Server uses its password file only when the enterprise server makes its first attempt at access (that is, when it starts up). File-level security is controlled by MSS itself, through the resource definitions you make.

The only way to maintain a password file is through this command line:

fs /pf pwd-filename options

Depending on the options you specify, Fileshare creates, modifies, or deletes pwd-filename. You can name the password file whatever you want, but it must correspond to the name you specify with the /pf option when configuring the Fileshare Server.

The options are as follows:

/u username | The user name used by the enterprise server to log onto the server. (This must correspond to the value specified in the FS user name field in the enterprise server's SIT.) Can be up to 20 characters.
/pw password | The enterprise server's password. (This must correspond to what is specified in the FS password field in the enterprise server's SIT.) Can be up to 20 characters.
/e | Erases the specified user from the password file. You must specify both the /u and /pw options on the same command line when you are using /e. If you delete all the entries in the password file, the Fileshare server deletes it.
Note: The user names and passwords are case-sensitive.

Examples

Assume no password file exists, and you want to create one with two entries. The following commands:

fs /pf fssecu.pwd /u Usr1 /pw fspass1
fs /pf fssecu.pwd /u Usr2 /pw fspass2

result in the password file fssecu.pwd being created, with entries for both Usr1 and Usr2. The Usr1/fspass1 and Usr2/fspass2 combinations must correspond to FS username and FS password fields in the enterprise server's SIT.

To put password checking into effect on a Fileshare Server called FSSERV (for example), you must use the /pf option when starting it:

fs /s fsserv /cm ccitcp /pf fssecu.pwd

To disable Usr2's access to this Fileshare Server, use the following command:

fs /pf fssecu.pwd /e /u Usr2 /pw fspass2

If you now enter this command:

fs /pf fssecu.pwd /e /u Usr1 /pw fspass1

Fileshare removes the entry for Usr1, and deletes the file fssecu.pwd.

Parent topic: Fileshare Server Configuration
Related information
Using a Fileshare Configuration File
Fileshare Options
Monitoring Fileshare Activity
FSView
Installing Fileshare as a Service
Optimizing the Fileshare Server
Starting a Fileshare Server


Monitoring Fileshare Activity

You can monitor the activity on a Fileshare server by pressing F2 from the same session in which you started the server. This turns on Fileshare's trace facility.

Tracing is written to the console window and also to a file called fsscreen.lst in your Fileshare directory. For each request, you see the user identifier, opcode, requested filename, and file status bytes of the reply to the user.

You should normally delete fsscreen.lst before starting a Fileshare server, otherwise your new trace output will be concatenated to whatever is currently in the file, which can be confusing when trying to track down problems.

You should use this facility only as a diagnostic aid, because it can degrade performance. Press F2 again to turn it off.

Parent topic: Fileshare Server Configuration
Related information
Using a Fileshare Configuration File
Fileshare Options
Using a Fileshare Password File
FSView
Installing Fileshare as a Service
Optimizing the Fileshare Server


FSView

FSView is a command-line utility for administering Fileshare servers. Some commands that control a Fileshare server cannot be entered at the Fileshare console window; these commands must be entered through FSView instead.

For a full list of FSView commands, see FSVIEW Command Line.

From the Fileshare console window, enter the command fsview to run in FSView mode, where you can enter a range of commands.

To use FSView mode to administer a Fileshare server, it must be started with Fileshare security, which is not set by default. To activate Fileshare security, the server must be started using a password file containing the special user ID FSVIEW and its password.

The password file should also contain the user name and password for each user who will be connecting to the Fileshare server. All clients then have to specify their user IDs and passwords when they connect.

See Walkthrough - Securing a Fileshare Server to create a password file containing the special user ID credentials, start a fileshare server securely using the file, and then log on to FSView to administer the server.

  • Walkthrough - Securing a Fileshare Server
Parent topic: Fileshare Server Configuration
Related reference
Fileshare Guide
Installing Fileshare as a Service
Related information
Using a Fileshare Configuration File
Fileshare Options
Using a Fileshare Password File
Monitoring Fileshare Activity
Installing Fileshare as a Service
Optimizing the Fileshare Server


Walkthrough - Securing a Fileshare Server

Here is a brief walkthrough to demonstrate FSView. In the following, you create the password file, start a Fileshare server, and then use the FSView utility to close it.

  1. At an application command prompt, in your Fileshare directory, enter:
    fs /pf pass.dat /u FSVIEW /pw Meryton

    This creates a password file called pass.dat, containing an entry for the user ID FSVIEW with password Meryton. The contents of this file are encrypted for secrecy.

    User IDs and passwords are case-sensitive.

    Note that the Fileshare server does not start, because you have not specified the /s parameter.

  2. To start a Fileshare server, enter:
    start fs /s server1 /pf pass.dat /sc
  3. At an application command prompt, still in the Fileshare directory, enter:
    fsview

    You now see the FSView command prompt.

  4. Give your logon credentials by entering the FSView command:
    admin logon FSVIEW Meryton
  5. To connect FSView to your Fileshare server and send the server your logon credentials, enter:
    server set server1
  6. To close the server, enter:
    server shutdown

    The server does not close yet. This command does not take effect until you exit from FSView.

  7. To close FSView, enter:
    exit

    FSView and the Fileshare server both close.

Parent topic: FSView
Related information
Fileshare Options


Installing Fileshare as a Service

Restriction: This is only applicable to Windows platforms.

You can install Fileshare as a Windows service by entering:

fsservice -i FS32SEV1 /wd C:\support\FS32\DATA /cf C:\support\FS32\FSAD32.CFG
at an application command prompt, where
FS32SEV1
A unique file name.
wd
The Fileshare working directory.
cf
The fully-qualified Fileshare server configuration file.
You can then start and stop it from the Windows Control Panel.

You uninstall Fileshare by entering:

fsservice -u

When you run Fileshare as a service, you must use a configuration file to pass your settings, and this file must be called fs.cfg. It must be in your c:\windows\system32 directory if the cf setting is not used.

In your configuration file, you can use the wd setting to specify your Fileshare directory. The wd setting can also be used when installing the service

When Fileshare is running as a service, you do not get a Fileshare console window, so cannot control it interactively via this window. Consequently:

  • You have to use FSView to control Fileshare and therefore must create a password file
  • We strongly recommend that you use sc, since it gives great performance gains, and the only reason for not using it was loss of interactive control.
  • You should specify /tr f in the configuration file if you want tracing, as you cannot use F2.
  • Walkthrough - Fileshare as a Service
Parent topic: Fileshare Server Configuration
Related information
Using a Fileshare Configuration File
Fileshare Options
Using a Fileshare Password File
Monitoring Fileshare Activity
FSView
Optimizing the Fileshare Server


Walkthrough - Fileshare as a Service

Restriction: This is only applicable to Windows platforms.

This example demonstrates several of the features described in this chapter. We'll start a Fileshare server, just as we did in the chapter Using Enterprise Server with Fileshare, but this time we'll use a configuration file, install Fileshare as a Windows service, and enable synchronous communications and tracing.

First make sure you do not have a Fileshare server currently running.

  1. Create file fs.cfg, containing:
    /s server1
/wd c:\fsdir
/pf pass.dat
/sc
/tr f
  2. Save this file to c:\windows\system32.
  3. If you have not already done so (you may have already done this in the Walkthrough - Securing a Fileshare Server in theFSView section), create file pass.dat in your c:\fsdir directory by entering:
    fs /pf pass.dat /u FSVIEW /pw Meryton

    The existence of this password file enables you to use FSView.

  4. To install the Fileshare service. at a command prompt, enter:
    fsservice -i

  5. Click Start > Control Panel > Administrative Tools > Services
  6. Select Micro Focus Fileshare Service and click Start.

    You can also if you wish double-click Micro Focus Fileshare Service and change its Startup Type to Automatic, so that it will start whenever you start Windows.

Parent topic: Installing Fileshare as a Service


Optimizing the Fileshare Server

There are a number of changes you can make to your Fileshare server to make it run faster.
  • Synchronous Communications
  • Processor Affinity
Parent topic: Fileshare Server Configuration
Related information
Using a Fileshare Configuration File
Fileshare Options
Using a Fileshare Password File
Monitoring Fileshare Activity
FSView
Installing Fileshare as a Service


Synchronous Communications

The Synchronous Communications option can improve performance up to the order of 10 times. You enable this simply by specifying the /sc parameter on the fs.exe command line.

This improves performance greatly but has no impact on the ability of the client (in this case an enterprise server) to interact with the Fileshare server.

However, it means Fileshare polls the keyboard very seldom, so it is impractical to administer Fileshare from the keyboard - for example, you cannot close a Fileshare server by entering Esc. Instead you must use the FSView utility, which is briefly described in the section FSView.

Parent topic: Optimizing the Fileshare Server
Related information
FSView


Processor Affinity

If your server machine is a multi-processor machine, you can use a mechanism called processor affinity for fs.exe. You can experiment with this setting via a popup menu accessible from the Process List on the Task Manager. Right-click fs.exe in the process list, and you can then select a context for the process. If you have the Windows Server resource kit installed, it includes a utility called imagecfg which you can use to permanently set processor affinity for a given .exe file.

Parent topic: Optimizing the Fileshare Server


Fileshare Client Configuration

  • Setting Up an MSS-enabled Enterprise Server as a Fileshare Client
    To enable enterprise server to be a Fileshare client, you must specify a valid user name and password (if security is set), the names of the Fileshare servers with which to connect, and the protocols used to connect.
  • Specifying Fileshare Servers in the RDF
    Within a resource definition file, you specify the resources that will reside on the Fileshare server
  • Configure the Files to Access via Fileshare
    Configure enterprise server to specify the files that can be accessed via the Fileshare server.
Parent topic: Configuration


Setting Up an MSS-enabled Enterprise Server as a Fileshare Client

If you have enabled Fileshare security, you must first give the enterprise server a valid Fileshare user name and password. These must be specified in the FS user name and FS password fields of the enterprise server's SIT. The enterprise server uses this user name and password combination to log on to all its Fileshare Servers. The combination must appear in the password file for each Fileshare server the enterprise server wants to access.

Next you should name the servers the enterprise server is to connect to. For data files you can have a choice of mechanisms for doing this:

  • Entries in the File Control Table (FCT) of the Resource Definition File (RDF)
  • Entries in the Fileshare client configuration file, fhredir.cfg

For extrapartition transient data queues and intrapartition transient data and temporary storage queues you must name the servers in the RDF; refer to Specifying Fileshare Servers in the RDF for more information. If you do not explicitly name the servers in the RDF, and you have an entry in the fhredir.cfg file that simply names a server (/s servername), then all file requests that do not have an explicit Fileshare server defined will be redirected to the named Fileshare server. If you are running multiple enterprise servers this will cause file contention problems.

Finally, you must specify the protocols over which the region communicates with its servers. You do this in the client configuration file fhredir.cfg.

MSS consults the fhredir.cfg file whenever a region requires a resource from a server. You should not, therefore, change this file while any regions using servers defined by it are running.

For full details of fhredir.cfg entries and examples see the chapters Standard Operation and Configuration in your Fileshare Guide

Parent topic: Fileshare Client Configuration
Related information
Specifying Fileshare Servers in the RDF
Configure the Files to Access via Fileshare


Specifying Fileshare Servers in the RDF

Through the resource definition file, you can specify that any of the following resources reside on a Fileshare server:

  • Application data files (through the FCT)
  • Extrapartition transient data queues (through the DCT)
  • Intrapartition transient data and temporary storage queues (through the SIT)

The FCT, DCT, and SIT contain fields for specifying the name of a Fileshare Server. If you fill one of these fields in, MSS looks for the resource on a Fileshare Server.

The FCT fields are on the FCT Details page of ESMAC.

The fields are:

Field | Description
Fileshare Server | The Fileshare Server through which MSS accesses the file. This name must correspond to the name you give the server when you start it. This field is mandatory.
Override Filename | The filename Fileshare uses to find the file. This field is optional. it defaults to the name of the FCT entry.
File Path | The path Fileshare uses to find the file. This field is optional. It must be specified if the path defined by the project does not exist on the Fileshare server machine.
File Extension

Specifies the file extension Fileshare uses to find the file. This field is optional. For indexed files, this results in a filename and its index component as follows:

  • filename.dat
  • filename.idx

The DCT fields are on the DCT Details page of ESMAC.

The fields are:

Field | Description
Fileshare | The Fileshare Server through which MSS accesses the file. This name must correspond to the name you give the server when you start it. This field is mandatory.
File Name

The filename Fileshare uses to find the file. This field is optional. The name defaults to the name of the DCT entry

The path Fileshare uses to find the file. This field is optional. It must be specified if the path defined by the project does not exist on the Fileshare server machine.

Extension

The file extension Fileshare uses to find the file. This field is optional. For indexed files, this results in a filename and its index component as follows:

  • filename.dat

  • filename.idx

In the SIT, there are two sets of fields through which you specify Fileshare Servers for temporary storage and intrapartition transient data queues. You do not have to specify the Fileshare Server and path for each individual queue.

The SIT fields are on the SIT Details page of ESMAC.

There are four sets of the following fields, one each for:

  • Recoverable temporary storage queues
  • Unrecoverable temporary storage queues
  • Recoverable transient data queues
  • Unrecoverable transient data queues

The fields are:

Field | Description
Fileshare Srvr | The Fileshare Server through which MSS accesses the file. This name must correspond to the name you give the server when you start it. This field is mandatory.
Path | The path Fileshare uses to find the file. This field is optional. It must be specified if the path defined by the project does not exist on the Fileshare server machine

Parent topic: Fileshare Client Configuration
Related information
Setting Up an MSS-enabled Enterprise Server as a Fileshare Client
Configure the Files to Access via Fileshare


Configure the Files to Access via Fileshare

Configure enterprise server to specify the files that can be accessed via the Fileshare server.
  • Format of the Fileshare Server Name
  • Accessing All Datasets via Fileshare
  • Accessing an Individual Dataset via FiIeshare
  • Dataset Created by a Batch Job
  • Accessing the Catalog via Fileshare
  • Files Accessed by Both CICS and JCL
  • Bulk Update of Catalog
Parent topic: Fileshare Client Configuration
Related information
Setting Up an MSS-enabled Enterprise Server as a Fileshare Client
Specifying Fileshare Servers in the RDF


Format of the Fileshare Server Name

Remember that a dataset is represented by a physical file on disk, and although the enterprise server can create a default name for the physical file there are various places where you can override this default and specify a name of your own choosing. To specify that a file is to be accessed via Fileshare, you specify the path and filename of the physical file and include in the path the name of the Fileshare server to use.

Wherever you specify the Fileshare server, you precede its name with "$$". For example:

$$server1
Parent topic: Configure the Files to Access via Fileshare
Related information
Accessing All Datasets via Fileshare
Accessing an Individual Dataset via FiIeshare
Dataset Created by a Batch Job
Accessing the Catalog via Fileshare
Files Accessed by Both CICS and JCL
Bulk Update of Catalog


Accessing All Datasets via Fileshare

You can configure an enterprise server so that all datasets are accessed via Fileshare.

In ES Admin, on the Edit page for the server, on the JES tab, include the name of the Fileshare server in the path for the Default Allocated Dataset Location. You then don't need to specify anything for individual datasets, unless you want to override this.

Changes made on this page are picked up when you next start the enterprise server.

Parent topic: Configure the Files to Access via Fileshare
Related information
Format of the Fileshare Server Name
Accessing an Individual Dataset via FiIeshare
Dataset Created by a Batch Job
Accessing the Catalog via Fileshare
Files Accessed by Both CICS and JCL
Bulk Update of Catalog


Accessing an Individual Dataset via FiIeshare

You can configure an individual dataset to be accessed via Fileshare, or by a specific Fileshare server overriding the one specified in the Default Allocated Dataset Location.

Go to the FCT page for the file (in ESMAC, select Start L on the Resources dropdown list, then click FCT, then click Details by the file), and then:

  • If the FCT entry is not linked to a catalog entry (there is no check mark by Use Catalog), look at the group of fields provided for specifying a physical filename to override the default location. Enter the name of the Fileshare server in the Fileshare Server field.
  • If the FCT entry is linked to a catalog entry, go to the Catalog page for the file (select JES on the Resources dropdown list, click Catalog, then click Details by the file) - you see a Physical File field provided for specifying a physical filename to override the default location. Include the name of the Fileshare server in the path/filename you specify here.

    (Because JCL does not need transactional VSAM access, the catalog page does not have an explicit Fileshare Server field as the FCT entry does. However, simply including the Fileshare server name in the path in the Physical File field does as well.)

In a similar way, you can specify that an extrapartition transient data file is to be accessed via Fileshare, by naming a Fileshare server on the file's DCT page in ESMAC. Also, the SIT page in ESMAC has four fields where you can specify that temporary storage queues (recoverable and non-recoverable) and intrapartition transient data files (recoverable and non-recoverable) are to be accessed via Fileshare.

Parent topic: Configure the Files to Access via Fileshare
Related information
Format of the Fileshare Server Name
Accessing All Datasets via Fileshare
Dataset Created by a Batch Job
Accessing the Catalog via Fileshare
Files Accessed by Both CICS and JCL
Bulk Update of Catalog


Dataset Created by a Batch Job

You can specify that an individual file created by JCL or IDCAMS is to be accessed via Fileshare, or by a specific Fileshare server overriding the one specified in the Default Allocated Dataset Location.

In the DD or DEFINE command that creates it, use the extension %PCDSN (see the chapter Extensions to JCL and IDCAMS ) to specify a physical filename to override the default location - include the name of the Fileshare server in the path/filename you specify here.

Parent topic: Configure the Files to Access via Fileshare
Related information
Format of the Fileshare Server Name
Accessing All Datasets via Fileshare
Accessing an Individual Dataset via FiIeshare
Accessing the Catalog via Fileshare
Files Accessed by Both CICS and JCL
Bulk Update of Catalog


Accessing the Catalog via Fileshare

You can configure an enterprise server so that the catalog itself is accessed via Fileshare.

In ES Admin, on the Edit page for the server, on the JES tab, include the name of the Fileshare server in the path for the System Catalog.

This also causes the spool files to be accessed via Fileshare.

Changes made on this page are picked up when you next start the enterprise server.

In the real world you would probably not put system files such as the catalog under the control of Fileshare, since accesses to these are managed by enterprise server and it would not bring any advantage, just the additional overhead of Fileshare communications.

Parent topic: Configure the Files to Access via Fileshare
Related information
Format of the Fileshare Server Name
Accessing All Datasets via Fileshare
Accessing an Individual Dataset via FiIeshare
Dataset Created by a Batch Job
Files Accessed by Both CICS and JCL
Bulk Update of Catalog


Files Accessed by Both CICS and JCL

If a batch job needs exclusive access to a dataset that is also accessed by CICS, then the dataset must be closed and disabled before the batch job can run. The batch job waits until this has been done before executing.

If the batch job does not require exclusive access, there is no problem - it can access the dataset at the same time as CICS.

You can use the casfile command to close and disable a dataset, and to open and enable it again after the batch job has finished with it. You call casfile from the application command prompt. You could call it indirectly from within a JCL jobstream, by writing a simple COBOL program to call it and then calling the COBOL program from the jobstream.

Here are some examples of casfile, showing its most important parameters. See casfile for full details.

To close and disable a file called payroll in an enterprise server called FSDEMO, enter:

casfile -rFSDEMO -oc -ed –dPAYROLL

Where:

  • -oc means set the Open status to "closed"
  • -ed means set the Enable status to "disabled"
  • the -d parameter gives the dataset name as shown in the FCT.

To open and enable the same file, enter:

casfile -rFSDEMO -ooi -ee –dPAYROLL

Where:

  • -ooi means to mark the FCT as open instructs CICS to physically open the file
  • -ee means set the Enable status to "enabled"

You can call casfile from a COBOL program via x"91" function 35 (not on UNIX), CBL_EXEC_RUN_UNIT or simply by CALL "CASFILE" using ..., where the input consists of a string containing the options that you use on the command line prefixed with its length, as indicated below.

01  lk-cmd-line.
        05  lk-cmd-len                pic x(02) comp-x.
        05  lk-cmd-data               pic x(1024).

A return code of 0 indicates success. Any other value indicates an error.

Parent topic: Configure the Files to Access via Fileshare
Related information
Format of the Fileshare Server Name
Accessing All Datasets via Fileshare
Accessing an Individual Dataset via FiIeshare
Dataset Created by a Batch Job
Accessing the Catalog via Fileshare
Bulk Update of Catalog


Bulk Update of Catalog

If you move a number of datasets from one place on your PC or PC network to another - from one directory to another, from one network server to another, or from the control of one Fileshare server to another - you need to make sure each one's catalog entry shows the new path in the physical filename.

If the catalog and the datasets reside together on the same path, there is no problem. By default, paths in the catalog are stored as relative paths (although they are expanded before being displayed), so the relocation of the files is reflected automatically.

However, if the catalog resides in a different location to the data files, you must update the catalog entries. You can update them all in one command, using the utility mvspcrn.exe in a COBOL command environment.

Before running the utility, you must set the environment variables:

  • MFSYSCAT - full path and filename of the catalog to be updated.

  • MFALLOC_LOC - full path of the Default Allocated Dataset Location.

In fact the value in MFALLOC_LOC is ignored, but it must be set. It's good practice to set it to the Default Allocated Dataset Location.

The format of the command line is:

mvspcrn old-string new-string [options]

Ensure old-string and new-string are enclosed in quotation marks if they contain filenames that include spaces.

The [options] are:

-y Specifies quiet mode - no prompts are given

In each catalog entry where the physical filename (including path) starts with old-string, old-string is replaced by new-string.

If the quiet mode option is not set the utility displays two prompts, asking you to confirm the setting of MFSYSCAT and the parameters, and then updates the catalog.

The parameters are not case sensitive.

The utility does not actually move or rename any files. It only updates their catalog entries.

The utility affects entries for spool files as well as entries for cataloged datasets.

We strongly recommend that you back up your catalog before running this utility. Check that your MFSYSCAT points to the correct catalog.

old-string is compared to the string actually stored in the catalog, so, in the case of a file accessed via a Fileshare server, old-string should start with the Fileshare server name preceded by $$.

  • Examples
Parent topic: Configure the Files to Access via Fileshare
Related information
Format of the Fileshare Server Name
Accessing All Datasets via Fileshare
Accessing an Individual Dataset via FiIeshare
Dataset Created by a Batch Job
Accessing the Catalog via Fileshare
Files Accessed by Both CICS and JCL


Examples

In all these examples, we'll assume your catalog is c:\catalog\catalog.dat.

  • Example 1
  • Example 2
  • Example 3
  • Example 4
  • Example 5
Parent topic: Bulk Update of Catalog


Example 1

You have a set of datasets in directory c:\datasets and you move them all to e:\datasets. To update the catalog:

set mfsyscat=c:\catalog\catalog.dat
set mfalloc_loc=e:\datasets
mvspcrn c e
Parent topic: Examples


Example 2

You have a set of datasets in directory c:\datasets and you move them all to e:\data. To update the catalog:

set mfsyscat=c:\catalog\catalog.dat
set mfalloc_loc=e:\datasets
mvspcrn c:\datasets e:\data
Parent topic: Examples


Example 3

You have a set of datasets accessed via Fileshare server server1. They are in c:\fsdir\datasets, where c:\fsdir is the Fileshare directory for server1. You do not move the datasets, but you stop the server and restart it with a different name, server2. To update the catalog:

set mfsyscat=c:\catalog\catalog.dat
set mfalloc_loc=$$server1\datasets
mvspcrn $$server1 $$server2
Parent topic: Examples


Example 4

You have a set of datasets accessed via Fileshare server server1. They are in c:\fsdir\datasets, where c:\fsdir is the Fileshare directory for server1. You move the datasets to c:\fs2dir\data, where c:\fs2dir is the Fileshare directory for server2. In future you want to access them via server2. To update the catalog:

set mfsyscat=c:\catalog\catalog.dat
set mfalloc_loc=$$server1\datasets
mvspcrn $$server1\datasets $$server2\data
Parent topic: Examples


Example 5

You have a set of datasets accessed via Fileshare server server1. They are in c:\fsdir\datasets, where c:\fsdir is the Fileshare directory for server1. Those associated with your payroll application all have names beginning payroll, and you move these to c:\fs2dir\data, where c:\fs2dir is the Fileshare directory for server2. In future you want to access these files via server2. To update the catalog:

set mfsyscat=c:\catalog\catalog.dat
set mfalloc_loc=$$server1\datasets
mvspcrn $$server1\datasets\payroll $$server2\data\payroll
Parent topic: Examples


Walkthrough

The configuration you create in this walkthrough makes all I/O for applications running in your enterprise server go via a Fileshare server.

  1. Configure the Fileshare Server
  2. Add an Enterprise Server
  3. Configure All Datasets to go via Fileshare
  4. Run a JCL Job
Parent topic: Stand-alone Fileshare


Configure the Fileshare Server

In this walkthrough, it is assumed that your Fileshare server runs on the same machine as your enterprise server. You will create a directory to use as the Fileshare directory, and within this, create a subdirectory to contain the user files created and accessed by applications.

  1. Start an application command prompt.
  2. Create a directory called fsdir, and then within it create a subdirectory datasets.

  3. Change into the directory that you just created, and enter:

    start fs /s server1

    Note: To add tracing to the Fileshare server, append /tr f, or press F2.

    Tracing is written to the console window and also to a file called fsscreen.lst in your Fileshare directory. You should normally delete fsscreen.lst before starting a Fileshare server, otherwise your new trace output will be concatenated to whatever is currently in the file, which can be confusing when trying to track down problems.

    This starts a Fileshare server named server1.

    The Fileshare console window appears, as shown below.

    Fileshare console window

    If you have the ES Admin home page visible at this point, you may notice that an entry appears for server1. This is because Fileshare is implemented using Micro Focus' Common Communications Interface (CCI), and a Fileshare server is an example of a CCI server. ES Admin shows CCI servers as well as enterprise servers. The current status is shown as Registered.

Parent topic: Walkthrough
Next topic: Add an Enterprise Server


Add an Enterprise Server

We will create a new enterprise server to use for this walkthrough. You could alternatively apply your changes to an existing enterprise server.

  1. On the ES Admin home page, click Add.
  2. Enter FSDEMO as the name for the new server, and click Next.
  3. Select Micro Focus Enterprise Server with Mainframe Subsystem Support to make it MSS-enabled. Click Next.
  4. Click Add.
Parent topic: Walkthrough
Previous topic: Configure the Fileshare Server
Next topic: Configure All Datasets to go via Fileshare


Configure All Datasets to go via Fileshare

We next configure this enterprise server to send all I/O requests for all datasets accessed by applications running in it to the Fileshare server.

  1. On the ES Admin home page, click Edit next to FSDEMO.
  2. Click the MSS tab, select Mainframe Subsystem Support enabled, then click Apply.
  3. Click the JES tab, then select Job Entry Subsystem enabled.
  4. Complete the following fields:
    JES Program Path | The path for the directory containing executable files to be run by your JCL jobs.
    System Catalog | The path and file name of the system catalog. This is a file that holds the details of data files, their attributes and locations.
    Default Allocated Dataset Location The $$ format of the Fileshare server to use. In this example, also include the name of the subdirectory you created previously; for example:
    \$\$server1\datasets
    System Procedure Library | The set of cataloged PDS data set names that will be searched to resolve JCL procedure names.
  5. Click Apply.

  6. You now need to start FSDEMO. You will find steps in the next section more convenient if you start it from the command line rather than from ES Admin. So, in your application command prompt, enter:

    casstart /rFSDEMO

Parent topic: Walkthrough
Previous topic: Add an Enterprise Server
Next topic: Run a JCL Job


Run a JCL Job

Important: If you are using Microsoft Internet Explorer's Enhanced Security Configuration feature you must disable it before following this procedure. For example:
  1. Close all instances of Internet Explorer.
  2. Select Start > Administrative Tools > Server Manager. If a User Account Control dialog box appears, click Continue.
  3. Under Security Summary, choose Configure IE ESC.
  4. Make sure both Administrators and Users are not selected.
  5. Click OK.

Now that your Fileshare server server1 and your enterprise server FSDEMO are both running, we will run a simple JCL jobstream to verify that new datasets are created correctly and that everything is working.

  1. Create an iefbr14.jcl file in the fsdir directory.
  2. Open the file in a text editor and copy the code below in it:
    //DMFBR14  JOB 'DMFBR14',CLASS=A,MSGCLASS=A
//STEP1    EXEC PGM=IEFBR14
//SYSOUT   DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//DD1      DD DSN='DMF.TEST.DSN',DISP=(MOD,DELETE)
//DD2      DD DSN='DMF.TEST.DSN2',DISP=(MOD,DELETE)
//*

  3. Because you used the casstart command to start FSDEMO, you can submit the JCL from the Enterprise Developer command line. In your fsdir directory, enter:

    cassub /rFSDEMO /jc:\fsdir\iefbr14.jcl

    If you had started FSDEMO via ES Admin, you would have had to submit the JCL using the JES Control page in ESMAC.

    The job is parsed and then waits for a batch initiator to run it.

  4. In ES Admin, click Details in the Current Status column of FSDEMO, and then click ES Monitor and Control.
  5. With JES selected in the Resources list, click Control to display the JES Control page.
  6. Type A in the Classes field and click Start to start a class A initiator.

    The JCL job runs.

  7. Click Spool to display the JES Spool page and click the Output radio button. You should see something similar to the following:

  8. Select the DMFBR14 check box and click Display to display the details for the DMFBR14 jobstream, as follows:

  9. Click Details next to the SYSLOG.

    You should see something similar to the following. Note how the Physical File field is qualified using the Fileshare server name.

  10. Click Display.

    You should see the joblog displayed below. The PC filenames have now been resolved to be qualified by the Fileshare server name. ($$SERVER1).

  11. Click Back, and then click Catalog to display the JES Catalog page. Click DCB to the right of the entry for the newly created dataset DMF.TEST.DSN.

    Details for the catalog entry are displayed.

    Catalog Entry for Created Dataset

You have now verified that everything is configured and working.

Parent topic: Walkthrough
Previous topic: Configure All Datasets to go via Fileshare


Running EZASOKET Applications on Enterprise Server

Enterprise Server with Mainframe Subsystem Support can run CICS and JCL applications that use the EZASOKET APIs. Applications use the features provided by these APIs to establish and manage connections, and to exchange data, over TCP/IP networks.

This section describes the support of EZASOKET in Enterprise Server. It does not provide a guide to EZASOKET programming.

For instructions on developing CICS and JCL applications to run on Enterprise Server, please see your Mainframe Subsystem Support Developer's Guide.

  • Introduction
  • Prerequisites
  • Supplied Transactions and Programs
  • Items Omitted from this Release
  • Notes on individual functions
  • Configuring and Managing EZASOKET Support for CICS Applications
Parent topic: MSS Configuration and Administration


Introduction

Micro Focus EZASOKET is designed to emulate, as closely as possible, the IBM implementation documented in SC31-8518-01, "OS/390 SecureWay Communications Server: IP CICS Sockets Guide Version 2 Release 8" (1999). It also supports some, though not all, of the features introduced in the z/OS implementation documented in SC31-8807-02, "z/OS Communications Server: IP CICS Sockets Guide Version 1 Release 5" (2004).

However, there are some differences. Micro Focus EZASOKET makes use of the local platform's native TCP/IP support. Due to differences between TCP/IP implementations, there are some circumstances in which Micro Focus EZASOKET does not behave identically to the IBM implementation. These differences are documented in the section Notes on individual functions.

Parent topic: Running EZASOKET Applications on Enterprise Server
Related information
Notes on individual functions


Prerequisites

You must have Enterprise Developer with Mainframe Subsystem Support.

You must ensure that your enterprise server has Mainframe Subsystem Support enabled.

You must specify a suitable SIT for your enterprise server.

To run CICS applications on your enterprise server:

  • You must ensure that you have a TN3270 listener defined
  • You may also need to define the CICS search paths

To use JCL with an enterprise server, you must:

  • Enable JES for the server
  • Define batch initiators and printers for the server

You may also need to define the JES program paths in Enterprise Server Administration.

To ensure 64-bit applications that use EZASOKET work correctly, you must compile these applications with the compiler directive AMODE set.

Note: Beyond the requirements stated above, the support of EZASOKET for JCL does not need any special configuration. EZASOKET CICS support needs additional configuration as described in the section Configuring and managing EZASOKET support for CICS applications.
Parent topic: Running EZASOKET Applications on Enterprise Server
Related information
To enable MTO for an enterprise server
To change the SIT associated with a server
To specify a listener for TN3270 terminals
To configure CICS search paths
To enable JCL support
To define a batch initiator or printer SEP
Configuring and managing EZASOKET support for CICS applications


Supplied Transactions and Programs

This section lists the programs and transactions supplied with Enterprise Server.

  • Standard Transactions and Programs
  • Test Transactions
  • Demonstration Programs
Parent topic: Running EZASOKET Applications on Enterprise Server


Standard Transactions and Programs

For more information on these items, please refer to the IBM document SC31-8807-02, "z/OS Communications Server: IP CICS Sockets Guide Version 1 Release 5".

  • DFHEZA: group containing the EZASOKET definitions for CICS
  • EZAC: transaction to define/alter/display/delete the CICS/Sockets listeners
  • EZAO: transaction to start/stop CICS/Sockets listeners
  • EZACIC20: program used in PLTPI/PLTSD or as a linked program to start/stop CICS/Sockets listeners
  • EZACICSE: (default security exit, ASCII) can be replaced with your own exit
  • EZACIC02: (default listener IPv4) can be replaced by your own listener
  • EZACIC04: EBCDIC to ASCII translation program
  • EZACIC05: ASCII to EBCDIC translation program
  • EZACIC14: EBCDIC to ASCII translation program using a fixed table
  • EZACIC15: ASCII to EBCDIC translation program using a fixed table
  • EZACIC06: Translates bit-masks into character arrays and character arrays into bit-masks
  • EZACIC08: Interprets the variable length address list in the HOSTENT structure returned by GETHOSTBYNAME or GETHOSTBYADDR.
  • EZACIC25: Domain Name Server (DNS) cache module emulation
Parent topic: Supplied Transactions and Programs


Test Transactions

  • EZPI: transaction to test CICS/Sockets listener CSKL is defined properly
  • EZPO: transaction used by EZPI to test CICS/Sockets is defined properly
Parent topic: Supplied Transactions and Programs


Demonstration Programs

  • EZAPING: Client demo program
  • EZAPONG: Server demo program started by EZAPING
Parent topic: Supplied Transactions and Programs


Items Omitted from this Release

The features not available this release are:

  • IPv6 support
  • raw sockets
  • multicasting
  • full support for Out-Of-Band (OOB) data

The following APIs are not available:

  • FREEADDRINFO
  • GETADDRINFO
  • GETNAMEINFO
  • INITAPIX
  • READV
  • RECVMSG
  • SENDMSG
  • WRITEV

The EZACIC09 utility program (which is used with GETADDRINFO) is not included in this release.

The CICS Domain Name System Cache is not included in this implementation. However, the API for it (utility program EZACIC25) is included, so you do not need to change application programs that use the DNS Cache.

WLM (Work Load Manager) registration for listeners is not supported.

Parent topic: Running EZASOKET Applications on Enterprise Server


Notes on individual functions

There are additional considerations for the following EZASOKET functions:

  • GETHOSTBYADDR
  • GETHOSTBYNAME
  • GETSOCKNAME
  • GETSOCKOPT
  • GIVESOCKET
  • INITAPI
  • IOCTL
  • SELECT
  • SETSOCKOPT
  • SOCKET
  • TAKESOCKET
  • Security Exit
Parent topic: Running EZASOKET Applications on Enterprise Server


GETHOSTBYADDR

Where a hostname cannot be resolved, the function returns a RETCODE of -1 and null pointer for HOSTENT. This is in line with the behaviour of versions of IBM EZASOKET that were tested. However, the IBM documentation states that, if the hostname cannot be resolved, the function will return a HOSTENT structure containing the error code. The behaviour of this function may change in future releases. We recommend that application programs rely on the RETCODE value to determine whether the call succeeded, and only inspect the HOSTENT structure if RETCODE is 0.

The GETHOSTBYADDR function is not thread-safe.

Because the native name resolution functions used by Micro Focus are not thread-safe, there is a very small possibility of a race condition occurring and of the function returning incorrect data. However, this is significantly less likely than errors elsewhere in the name resolution system, such as a failing DNS server.

Parent topic: Notes on individual functions


GETHOSTBYNAME

See GETHOSTBYADDR above.

Parent topic: Notes on individual functions


GETSOCKNAME

The IBM documentation states that if GETSOCKNAME is passed a socket that does not have a local address, GETSOCKNAME will return successfully (RETCODE = 0), with the FAMILY field of the NAME parameter set to 2 and the other fields set to 0. The Micro Focus implementation may return an error in this case.

Parent topic: Notes on individual functions


GETSOCKOPT

Only the following operations are supported:

  • SO_ACCEPTCONN
  • SO_BROADCAST
  • SO_DEBUG
  • SO_ERROR
  • SO_KEEPALIVE
  • SO_LINGER
  • SO_RCVBUF
  • SO_REUSEADDR
  • SO_SNDBUF
  • SO_TYPE
  • TCP_NODELAY
Parent topic: Notes on individual functions


GIVESOCKET

The CLIENT parameter is ignored. That is, this version does not support restricting which tasks can take a socket.

Cross-region GIVESOCKET is not supported.

Parent topic: Notes on individual functions


INITAPI

The IDENT and SUBTASK parameters are ignored.

No task may have more than 4096 sockets.

Parent topic: Notes on individual functions


IOCTL

Only the FIONBIO and FIONREAD operations are supported.

Parent topic: Notes on individual functions


SELECT

The reporting of exception conditions, tested for by use of the ESNDMSK parameter, differs between platforms. This is due to differences between TCP/IP implementations on those platforms.

Where a socket specified with the ESNDMSK parameter has been the subject of a GIVESOCKET, but has not yet been the subject of a TAKESOCKET, SELECT will continue to poll the socket until the TAKESOCKET occurs. In addition, SELECT cannot test sockets which are in this "given" state for normal I/O events.

Parent topic: Notes on individual functions


SETSOCKOPT

Only the following operations are supported:

  • SO_BROADCAST
  • SO_DEBUG
  • SO_KEEPALIVE
  • SO_LINGER
  • SO_RCVBUF
  • SO_RCVTIMEO1
  • SO_REUSEADDR
  • SO_SNDBUF
  • SO_SNDTIMEO2
  • TCP_NODELAY
Parent topic: Notes on individual functions
1
Restriction: The behavior when this option is used depends on the support provided by the underlying Operating System and might not match the behavior on the mainframe.
2
Restriction: The behavior when this option is used depends on the support provided by the underlying Operating System and might not match the behavior on the mainframe.


SOCKET

The value of the PROTO parameter passed by the caller is ignored.

Only STREAM and DGRAM sockets are supported.

Parent topic: Notes on individual functions


TAKESOCKET

Only the TASK field of the CLIENT parameter is used. Other fields are ignored.

See GIVESOCKET above for more information on the limitations of GIVESOCKET and TAKESOCKET in this release.

Note: Note:

If you create your own EZASOKET listener, you must compile it with the directive CALL-RECOVERY.

Parent topic: Notes on individual functions


Security Exit

The CICS EZASOKET Security Exit should be compiled with directive charset(ASCII) as all the parameters are expected to be passed in ASCII and returned in ASCII.

Parent topic: Notes on individual functions


Configuring and Managing EZASOKET Support for CICS Applications

This assumes that you have already configured your Enterprise Server to run CICS applications as detailed in the chapter CICS Walkthrough in your Mainframe Subsystem Support Developer's Guide. You also need to ensure that you have updated your Resource Definition Files. See the section Updating Existing Resource Definitions in the chapter Configuring Enterprise Edition/MSS of your Enterprise Server Extending CICS and IMS Applications Guide.

  • Enabling EZASOKET Support in Enterprise Server
  • Adding DFHEZA Group to your CICS Startup List
  • Restarting the Enterprise Server
  • Understanding EZASOKET Configuration
  • Using the Configuration Transaction (EZAC)
  • Starting and Stopping the EZASOKET Interface Automatically
  • Starting and Stopping the EZASOKET Interface with a Program Link
  • Starting/Stopping the EZASOKET Interface and Listeners Manually
  • Testing that EZASOKET Support is Correctly Installed and Configured
  • Sockets return codes (ERRNOs)
    The system-wide message numbers and codes set by the system calls.
Parent topic: Running EZASOKET Applications on Enterprise Server


Enabling EZASOKET Support in Enterprise Server

To enable EZASOKET support you must either set the environment variable ES_EZASOKET_SUPPORT=YES or take the following steps:

  1. Connect to Enterprise Server Administration.
  2. In the table of servers on the Home page of Enterprise Server Administration, find the row for the server that you using as your CICS region, and click Edit in the left hand column.
  3. Click Properties > MSS.
  4. Check EZASOKET support.
  5. Click OK.
  6. If the enterprise server is started, please stop it.
  7. Restart the server.
Parent topic: Configuring and Managing EZASOKET Support for CICS Applications
Related information
To access Enterprise Server Administration
To stop an enterprise server
To start an enterprise server


Adding DFHEZA Group to your CICS Startup List

  1. On the Home page of Enterprise Server Administration, click Details in the Current Status column for your enterprise server.
  2. Click ES Monitor & Control.
  3. In the Resources panel, which is about half way down on the left, expand the drop-down list and select by Group.

    The buttons in the Resources panel change to indicate the options for viewing and managing resources by group.

  4. Click StartUp in the Resources panel.
  5. Click Details for your startup list.

    This displays the contents of your startup list.

  6. Type DFHEZA in the first empty field.
  7. Click Apply.
Parent topic: Configuring and Managing EZASOKET Support for CICS Applications


Restarting the Enterprise Server

To make the enterprise server pick up the configuration changes you just made, you have to stop it and restart it.

  1. Stop the enterprise server.
  2. Restart the enterprise server.
Parent topic: Configuring and Managing EZASOKET Support for CICS Applications
Related information
To stop an enterprise server
To start an enterprise server


Understanding EZASOKET Configuration

The EZASOKET configuration file (EZACONFG) contains details of CICS regions (that is, enterprise servers capable of running CICS applications) and the CICS listeners within those regions. The file can be shared by multiple enterprise servers. The location of the file used by your Enterprise Server is governed by the File Path configuration setting for the server.

For each CICS region that supports EZASOKET and is controlled by the configuration file, there is an associated object (referred to as a CICS object) in the configuration file. The object is identified by the APPLID of the CICS region. There is also a listener object for each listener defined for a CICS region.

The first task you will perform is to use the EZAC transaction to define a CICS object in the configuration file for your CICS region. If the configuration file does not exist, EZAC will create it.

EZACICM.MOD

In an out-of-the-box IVP installation, the Map Path field in the configuration is blank, so CICS will use the default map directory. That default map directory is where the EZACICM.MOD file is located. This path does not have to be set explicitly in an out-of-the-box install.

However, it is quite common to set a different Map Path when customizing Enterprise Server regions, to add directories where customer application map files are kept. If that is done, you may have to explicitly add the default directory to ensure EZACICM.MOD is found. The Enterprise Server will find the system directory with its EZACICM.MOD file after it finds the customer directory with its EZACICM.MOD file, so you may have to place the directory containing the EZACICM.MOD file so that it is found first.

It is preferable to rename the application files to avoid conflicts if possible.

Parent topic: Configuring and Managing EZASOKET Support for CICS Applications


Using the Configuration Transaction (EZAC)

The EZAC transaction enables you to add, delete, or modify items in the configuration file while your CICS region is running. The following table lists and describes the functions supported by the EZAC transaction.

Command | Object | Function
ALTER | CICS/Listener | Modifies the attributes of an existing resource definition
DEFINE | CICS/Listener | Creates a new resource definition
DISPLAY | CICS/Listener | Shows the parameters specified for the CICS/Listener object
DELETE CICS/Listener
  • CICS - Deletes the CICS object and all of its associated listeners
  • Listener - Deletes the listener object

Start a TN3270 session, connect to the port for the TN3270 listener on your enterprise server and start the EZAC transaction. When you enter EZAC, the following screen is displayed:

Figure 1. Initial EZAC screen
Initial EZAC screen

Enter the command you want to execute followed by the type of object. For creating a CICS object for your CICS region, you type:

EZAC DEF CICS or EZAC,DEF,CICS or EZAC,DEFINE,CICS or EZAC DEF and then select CICS on the screen. You are now presented with a screen in which you specify the CICS region for which you are configuring EZASOKET.

Figure 2. EZAC, Define, CICS screen
EZAC, Define, CICS screen

Enter the name of the CICS APPLID for which you are defining configuration information. In this case, the APPLID is the name of your enterprise server. The field defaults to this value.

When you press Enter, the following screen is displayed.

Figure 3. Application parameters screen
Application parameters screen

Specify the parameters you require for EZASOKET support in your CICS region. For more information, please refer to the IBM document SC31-8807-02, "z/OS Communications Server: IP CICS Sockets Guide Version 1 Release 5".

A CICS region will typically have one or more listeners. Each listener may be an instance of the supplied listener or a user-written listener. Define a CICS listener for your region using: EZAC DEF LIST or EZAC DEFINE LISTENER or EZAC,DEF,LIST or EZAC,DEFINE,LISTENER as shown in the following screenshots:

Figure 4. Listener screen
Listener screen

The following screen allows you to define the characteristics of your listener

Figure 5. Listener characteristics screen
Listener characteristics screen

For more information on this topic, please refer to the IBM document SC31-8807-02, "z/OS Communications Server: IP CICS Sockets Guide Version 1 Release 5".

Note:

The supplied transaction used in this example, CSKL, uses the default listener program, EZACIC02. This listener is written in ASCII. The rules described in the table below determine whether or not it converts the transaction id and the user data in the Transaction Initial Message from EBCDIC to ASCII.

TRANTRN | TRANUSR | Tranid format | Translate tranid? | Translate user data?
YES | YES | ASCII | NO | NO
YES | NO | ASCII | NO | NO
NO | YES | ASCII | NO | YES
NO | NO | ASCII | NO | NO
YES | YES | EBCDIC | YES | YES
YES | NO | EBCDIC | YES | NO
NO | YES | EBCDIC | YES | YES
NO | NO | EBCDIC | YES | NO
Parent topic: Configuring and Managing EZASOKET Support for CICS Applications


Starting and Stopping the EZASOKET Interface Automatically

You can enable automatic startup/shutdown of the EZASOKET interface by placing the EZACIC20 module in the appropriate Program List Table (PLT).

  1. Use the EZAC transaction to ALTER the attributes of the TN3270 listener for your enterprise server region, setting the option for IMMEDIATE to YES. For more information, see Using the Configuration Transaction (EZAC).
  2. On the Home page of Enterprise Server Administration, click Details in the Current Status column for your enterprise server.
  3. Click ES Monitor & Control.
  4. In the Resources panel, which is about half way down on the left, expand the drop-down list and select by Group.

    The buttons in the Resources panel change to indicate the options viewing and managing resources by group.

  5. Click SIT in the Resources panel.
  6. Click Details for your SIT table.
  7. Locate the Program Lists section.
  8. Enter the names you want to use for the Post Initialization and the Shut Down lists. For example:
    Post initialization
  9. Click Apply.

    You now create the program lists as described in the steps below.

  10. In the Resources panel, expand the drop-down list and select by Type.

    The buttons in the Resources panel change to indicate the options for viewing and managing resources by type.

  11. Click PLT in the Resources panel.

    The screen shows a list of CICS defined PLTs. At the bottom of the list is a set of buttons for creating new entries.

  12. Click PLT in the New section of the list.
  13. In Name, enter the name of your Post Initialization list.
  14. Click Grp to expand the drop-down list and select the group you want to use. This group must be defined in your Startup list.
  15. Enter a description in Description.
  16. In the row labelled 01:
    • In the first field, enter EZACIC20.
    • From the drop-down list, choose Run once.

    For example:
    Select group

  17. Click Add to save the new list.
  18. Click PLT in the Resources panel.
  19. Click PLT in the New section of the list.
  20. In Name, enter the name of your Shut Down list.
  21. Click Grp to expand the drop-down list and select the group you want to use. This group must be defined in your Startup list.
  22. Enter a description in Description.
  23. In the row labelled 01:
    • In the first field, enter EZACIC20.
    • From the drop-down list, choose Run once.
  24. Click Add to save the new list.
Parent topic: Configuring and Managing EZASOKET Support for CICS Applications
Related concepts
Using the Configuration Transaction (EZAC)


Starting and Stopping the EZASOKET Interface with a Program Link

You can start or stop the EZASOKET interface by issuing an EXEC CICS LINK to program EZACIC20. Make sure you include the following steps in the LINKing program:

  • Define the COMMAREA for EZACIC20. This can be done by including the EZACICA.CPY copybook in your program.
  • Initialize the COMMAREA values as follows:
    P20TYPE

    I Initialization

    T Immediate Termination

    D Deferred Termination
    P20OBJ

    C CICS EZASOKET interface

    L Listener
    P20LIST

    Name of listener if this is listener initialization/termination.
  • Issue the EXEC CICS LINK to program EZACIC20.
    Note:

    EZACIC20 will not return until the function is complete.

  • Check the P20RET field for the response from EZACIC20.
    Note:

    Note: If the EZASOKET interface is not in startup or termination and no COMMAREA was provided, the E20L user abend code is issued by EZACIC20.

Parent topic: Configuring and Managing EZASOKET Support for CICS Applications


Starting/Stopping the EZASOKET Interface and Listeners Manually

You can start the EZASOKET interface manually by using the EZAO transaction. This transaction has four functions:

  • Interface Startup

    Starts the interface in a CICS region and starts all listeners that are identified for immediate start.

    Note: The EZAO transaction must be running on the CICS region where you want to start the EZASOKET interface. You cannot start an EZASOKET interface from a different CICS.

  • Interface Shutdown

    Stops the interface in a CICS region.

  • Listener Startup

    Starts a listener in a CICS region.

  • Listener Shutdown

    Stops a listener in a CICS region.

You can type EZAO and select the action you require as shown below:

Figure 1. EZAO screen
EZAO screen

and then select the object that you want to act upon:

Figure 2. EZAO, Start
EZAO, Start

Alternatively, you can enter EZAO START|STOP CICS|LISTENER and then respond to the screen prompts as shown in the following examples:

Figure 3. EZAO, START, LISTENER
EZAO, START, LISTENER
Figure 4. EZAO, STOP, LISTENER(CSKL)
EZAO, STOP, LISTENER(CSKL)
Figure 5. EZAO, START, CICS
EZAO, START, CICS
Figure 6. EZAO, STOP, CICS
EZAO, STOP, CICS
Parent topic: Configuring and Managing EZASOKET Support for CICS Applications


Testing that EZASOKET Support is Correctly Installed and Configured

Using the transaction EZAC, alter an existing listener or define a new listener to test the supplied transaction EZPI as show below:

Figure 1. EZAC, ALTER, LISTENER
EZAC, ALTER, LISTENER

You can use any available port, but you must ensure that the fields TRANTRN and TRANUSR are set to NO.

Note:

You cannot use the same TRANID for more than one listener within a CICS region. Therefore, if you want to create a second instance of a listener, you must define a new transaction in a group specified in your startup list. For example, to create a new instance of the default listener, you create a new transaction and associate it with the default listener program, EZACIC02. You then use EZAC to create a new listener definition with the new transaction name as the TRANID.

Start the listener using EZAO. Once the listener has been started and the message EZY1291I appears on the console.log, run the demo transaction EZPI as shown in the examples below:

Figure 2. EZPI
EZPI
Figure 3. EZPI parameters
EZPI parameters

If everything is correctly installed and configured, you will get your message in reverse order in the Received field.

Figure 4. EZPI received
EZPI received
Parent topic: Configuring and Managing EZASOKET Support for CICS Applications


Sockets return codes (ERRNOs)

These message numbers and codes are in the TCPERRNO.H include file supplied with TCP/IP Services.

Error number | Message name | Socket type | Error description | Programmer's response
1 | EAI_NONAME | GETADDRINFO GETNAMEINFO | NODE or HOST cannot be found. | Ensure the NODE or HOST name can be resolved.
1 | EDOM | All | Argument too large. | Check parameter values of the function call.
1 | EPERM | All | Permission is denied. No owner exists. | Check that TPC/IP is still active; check protocol value of socket () call.
1 | EPERM | IOCTL (SIOCTTLSCTL requesting both TTLS_INIT_ CONNECTION and TTLS_RESET_ SESSION or both TTLS_INIT_ CONNECTION and TTLS_RESET_ CIPHER) | The combination of requests specified is not permitted. | Request TTLS_RESET_SESSION and TTLS_RESET_CIPHER only when TTLS_INIT_ CONNECTION has been previously requested for the connection.
1 EPERM IOCTL (SIOCTTLSCTL) Denotes one of the following error conditions:
  • The TTLS_INIT_ CONNECTION option was requested with either TTLS_RESET_ SESSION, TTLS_RESET_ CIPHER or TTLS_STOP_ CONNECTION
  • The TTLS_STOP_ CONNECTION option was requested along with TTLS_RESET_ SESSION or TTLS_RESET_ CIPHER
  • The TTLS_ALLOW_ HSTIMEOUT option was requested without TTLS_INIT_ CONNECTION
Request TTLS_RESET_SESSION and TTLS_RESET_CIPHER only when TTLS_INIT_ CONNECTION and TTLS_STOP_ CONNECTION are not requested. Always request TTLS_INIT_ CONNECTION when TTLS_ALLOW_ HSTIMEOUT is requested. Use seperate SIOCTTLSCTL ioctls to request TTLS_INIT_ CONNECTION and TTLS_STOP_ CONNECTION.
2 | EAI_AGAIN | FREEADDRINFO GETADDRINFO GETNAMEINFO | For GETADDRINFO, NODE could not be resolved within the configured time interval. For GETNAMEINFO, HOST could not be resolved within the configured time interval. The Resolver address space has not been started. The request can be retried later. | Ensure the Resolver is active, then retry the request.
2 | ENOENT | All | The data set or directory was not found. | Check files used by the function call.
2 | ERANGE | All | The result is too large. | Check parameter values of the function call.
3 | EAI_FAIL | FREEADDRINFO GETADDRINFO GETNAMEINFO | This is an unrecoverable error. NODELEN, HOSTLEN, or SERVLEN is incorrect. For FREEADDRINFO, the resolver storage does not exist. | Correct the NODELEN, HOSTLEN, or SERVLEN. Otherwise, call your system administrator.
3 | ESRCH | All | The process was not found. A table entry was not located. | Check parameter values and structures pointed to by the function parameters.
4 | EAI_OVERFLOW | GETNAMEINFO | The output buffer for the host name or service name was too small. | Increase the size of the buffer to 255 characters, which is the maximum size permitted.
4 | EINTR | All | A system call was interrupted. | Check that the socket connection and TCP/IP are still active.
5 | EAI_FAMILY | GETADDRINFO GETNAMEINFO | The AF or the FAMILY is incorrect. | Correct the AF or the FAMILY.
5 | EIO | All | An I/O error occurred. | Check status and contents of source database if this occurred during a file access.
6 | EAI_MEMORY | GETADDRINFO GETNAMEINFO | The resolver cannot obtain storage to process the host name. | Contact your system administrator.
6 | ENXIO | All | The device or driver was not found. | Check status of the device attempting to access.
7 | E2BIG | All | The argument list is too long. | Check the number of function parameters.
7 | EAI_BADFLAGS | GETADDRINFO GETNAMEINFO | FLAGS has an incorrect value. | Correct the FLAGS.
8 | EAI_SERVICE | GETADDRINFO | The SERVICE was not recognized for the specified socket type. | Correct the SERVICE.
8 | ENOEXEC | All | An EXEC format error occurred. | Check that the target module on an exec call is a valid executable module.
9 | EAI_SOCKTYPE | GETADDRINFO | The SOCTYPE was not recognized. | Correct the SOCTYPE.
9 | EBADF | All | An incorrect socket descriptor was specified. | Check socket descriptor value. It might be currently not in use or incorrect.
9 | EBADF | Givesocket | The socket has already been given. The socket domain is not AF_INET or AF_INET6. | Check the validity of function parameters.
9 | EBADF | Select | One of the specified descriptor sets is an incorrect socket descriptor. | Check the validity of function parameters.
9 | EBADF | Takesocket | The socket has already been taken. | Check the validity of function parameters.
9 | EAI_SOCKTYPE | GETADDRINFO | The SOCTYPE was not recognized. | Correct the SOCTYPE.
10 | ECHILD | All | There are no children. | Check if created subtasks still exist.
11 | EAGAIN | All | There are no more processes. | Retry the operation. Data or condition might not be available at this time.
12 | ENOMEM | All | There is not enough storage. | Check the validity of function parameters.
13 | EACCES | All | Permission denied, caller not authorized. | Check access authority of file.
13 | EACCES | Takesocket | The other application (listener) did not give the socket to your application. Permission denied, caller not authorized. | Check access authority of file.
13 | EACCES | IOCTL (SIOCTTLSCTL) | The IOCTL is requesting a function that requires that the socket be mapped to policy that specifies ApplicationControlled On. | Check policy and add ApplicationControlled On if the application should be permitted to issue the controlled SIOCTTLSCTL functions.
14 | EFAULT | All | An incorrect storage address or length was specified. | Check the validity of function parameters.
14 | EFAULT | IOCTL (SIOCSAPPLDATA) | An abend occurred while attempting to copy the SetADcontainer structure from the address provided in the SetAD_ptr field. | Check the validity of function parameters.
15 | ENOTBLK | All | A block device is required. | Check device status and characteristics.
16 | EBUSY | All | Listen has already been called for this socket. Device or file to be accessed is busy. | Check if the device or file is in use.
17 | EEXIST | All | The data set exists. | Remove or rename existing file.
18 | EXDEV | All | This is a cross-device link. A link to a file on another file system was attempted. | Check file permissions.
19 | ENODEV | All | The specified device does not exist. | Check file name and if it exists.
20 | ENOTDIR | All | The specified directory is not a directory. | Use a valid file that is a directory.
21 | EISDIR | All | The specified directory is a directory. | Use a valid file that is not a directory.
22 | EINVAL | All types | An incorrect argument was specified. | Check the validity of function parameters.
22 | EINVAL | Multicast Source filter APIs | Mix of any-source, source-specific or full-state APIs | Specify the correct type of APIs.
22 | EINVAL | MCAST_JOIN_GROUP, MCAST_JOIN_SOURCE_ GROUP, MCAST_BLOCK_SOURCE, MCAST_LEAVE_GROUP, MCAST_LEAVE_SOURCE_ GROUP, MCAST_UNBLOCK_ SOURCE, SIOCGMSFILTER, SIOCSMSFILTER | The socket address family or the socket length of the input multicast group or the source IP address is not correct. | Specify the correct value.
22 | EINVAL | SIOCSMSFILTER, SIOCSIPMSFILTER | The specified filter mode is not correct. | Specify the correct value.
23 | ENFILE | All | Data set table overflow occurred. | Reduce the number of open files.
24 | EMFILE | All | The socket descriptor table is full. | Check the maximum sockets specified in MAXDESC().
25 | ENOTTY | All | An incorrect device call was specified. | Check specified IOCTL() values.
26 | ETXTBSY | All | A text data set is busy. | Check the current use of the file.
27 | EFBIG | All | The specified data set is too large. | Check size of accessed dataset.
28 | ENOSPC | All | There is no space left on the device. | Increase the size of accessed file.
29 | ESPIPE | All | An incorrect seek was attempted. | Check the offset parameter for seek operation.
30 | EROFS | All | The data set system is Read only. | Access data set for read only operation.
31 | EMLINK | All | There are too many links. | Reduce the number of links to the accessed file.
32 | EPIPE | All | The connection is broken. For socket write/send, peer has shut down one or both directions. | Reconnect with the peer.
32 | EPIPE | IOCTL (SIOCTTLSCTL requesting TTLS_INIT_ CONNECTION, TTLS_RESET_CIPHER, or TTLS_STOP_ CONNECTION) | The TCP connection is not in the established state. | Issue the SIOCTTLSCTL IOCTL when the socket is connected.
33 | EDOM | All | The specified argument is too large. | Check and correct function parameters.
34 | ERANGE | All | The result is too large. | Check function parameter values.
35 | EWOULDBLOCK | Accept | The socket is in nonblocking mode and connections are not queued. This is not an error condition. | Reissue Accept().
35 | EWOULDBLOCK | Read Recvfrom | The socket is in nonblocking mode and read data is not available. This is not an error condition. | Issue a select on the socket to determine when data is available to be read or reissue the Read()/Recvfrom().
35 | EWOULDBLOCK | Send Sendto Write | The socket is in nonblocking mode and buffers are not available. | Issue a select on the socket to determine when data is available to be written or reissue the Send(), Sendto(), or Write().
35 | EWOULDBLOCK | IOCTL (SIOCTTLSCTL) | The handshake is in progress and the socket is a non-blocking socket. | For a non-blocking socket, you can wait for the handshake to complete by issuing Select or Poll for Socket Writable.
36 | EINPROGRESS | Connect | The socket is marked nonblocking and the connection cannot be completed immediately. This is not an error condition. | See the Connect() description for possible responses.
36 | EINPROGRESS | IOCTL (SIOCTTLSCTL requesting TTLS_INIT_ CONNECTION or TTLS_STOP_ CONNECTION) | The handshake is already in progress and the socket is a non-blocking socket. | For a non-blocking socket, you can wait for the handshake to complete by issuing Select or Poll for Socket Writable.
37 | EALREADY | Connect | The socket is marked nonblocking and the previous connection has not been completed. | Reissue Connect().
37 | EALREADY | IOCTL (SIOCTTLSCTL requesting TTLS_INIT_ CONNECTION or TTLS_STOP_ CONNECTION) | For TTLS_INIT_ CONNECTION, the socket is already secure. For TTLS_STOP_ CONNECTION, the socket is not secure. | Modify the application so that it issues the SIOCTTLSCTL IOCTL that requests TTLS_INIT_ CONNECTION only when the socket is not already secure and that requests TTLS_STOP_ CONNECTION only when the socket is secure.
37 | EALREADY | Maxdesc | A socket has already been created calling Maxdesc() or multiple calls to Maxdesc(). | Issue Getablesize() to query it.
37 | EALREADY | Setibmopt | A connection already exists to a TCP/IP image. A call to SETIBMOPT (IBMTCP_IMAGE), has already been made. | Only call Setibmopt() once.
38 | ENOTSOCK | All | A socket operation was requested on a nonsocket connection. The value for socket descriptor was not valid. | Correct the socket descriptor value and reissue the function call.
39 | EDESTADDRREQ | All | A destination address is required. | Fill in the destination field in the correct parameter and reissue the function call.
40 | EMSGSIZE | Sendto Sendmsg Send Write | The message is too long. It exceeds the IP limit of 64K or the limit set by the setsockopt() call. | Either correct the length parameter, or send the message in smaller pieces.
41 | EPROTOTYPE | All | The specified protocol type is incorrect for this socket. | Correct the protocol type parameter.
41 | EPROTOTYPE | IOCTL (SIOCTTLSCTL) | Socket is not a TCP socket. | Issue the SIOCTTLSCTL IOCTL on TCP sockets only.
41 | EPROTOTYPE | IOCTL (SIOCSAPPLDATA) | The request was not successful. The socket is not a stream (TCP) socket. | Issue the SIOCSAPPLDATA IOCTL on TCP sockets only.
42 | ENOPROTOOPT | Getsockopt Setsockopt | The socket option specified is incorrect or the level is not SOL_SOCKET. Either the level or the specified optname is not supported. | Correct the level or optname.
42 | ENOPROTOOPT | Getibmsockopt Setibmsockopt | Either the level or the specified optname is not supported. | Correct the level or optname.
43 | EPROTONOSUPPORT | Socket | The specified protocol is not supported. | Correct the protocol parameter.
44 | ESOCKTNOSUPPORT | All | The specified socket type is not supported. | Correct the socket type parameter.
45 | EOPNOTSUPP | IOCTL | The specified IOCTL command is not supported by this socket API. | Correct the IOCTL COMMAND.
45 | EOPNOTSUPP | GETSOCKOPT | The specified GETSOCKOPT OPTNAME option is not supported by this socket API. | Correct the GETSOCKOPT OPTNAME option.
45 | EOPNOTSUPP | IOCTL (SIOCTTLSCTL requesting TTLS_INIT_ CONNECTION, TTLS_RESET_ SESSION, TTLS_RESET_ CIPHER or TTLS_STOP_ CONNECTION) | Mapped policy indicates that AT-TLS is not enabled for the connection. | Modify the policy to enable AT-TLS for the connection.
45 | EOPNOTSUPP | RECV, RECVFROM, RECVMSG, SEND, SENDTO, SENDMSG | The specified flags are not supported on this socket type or protocol. | Correct the FLAG.
45 | EOPNOTSUPP | Accept Givesocket | The selected socket is not a stream socket. | Use a valid socket.
45 | EOPNOTSUPP | Listen | The socket does not support the Listen call. | Change the type on the Socket() call when the socket was created. Listen() only supports a socket type of SOCK_STREAM.
45 | EOPNOTSUPP | Getibmopt Setibmopt | The socket does not support this function call. This command is not supported for this function. | Correct the command parameter. See Getibmopt() for valid commands. Correct by ensuring a Listen() was not issued before the Connect().
46 | EPFNOSUPPORT | All | The specified protocol family is not supported or the specified domain for the client identifier is not AF_INET=2. | Correct the protocol family.
47 | EAFNOSUPPORT | Bind Connect Socket | The specified address family is not supported by this protocol family. | For Socket(), set the domain parameter to AF_INET. For Bind() and Connect(), set Sin_Family in the socket address structure to AF_INET.
47 | EAFNOSUPPORT | Getclient Givesocket | The socket specified by the socket descriptor parameter was not created in the AF_INET domain. | The Socket() call used to create the socket should be changed to use AF_INET for the domain parameter.
47 | EAFNOSUPPORT | IOCTL | You attempted to use an IPv4-only ioctl on an AF_INET6 socket. | Use the correct socket type for the ioctl or use an ioctl that supports AF_INET6 sockets.
48 | EADDRINUSE | Bind | The address is in a timed wait because a LINGER delay from a previous close or another process is using the address. This error can also occur if the port specified in the bind call has been configured as RESERVED on a port reservation statement in the TCP/IP profile. | If you want to reuse the same address, use Setsockopt() with SO_REUSEADDR. Refer to the section about Setsockopt() in z/OS Communications Server: IP Sockets Application Programming Interface Guide and Reference for more information. Otherwise, use a different address or port in the socket address structure.
48 | EADDRINUSE | IP_ADD_MEMBERSHIP, IP_ADD_SOURCE_ MEMBERSHIP, IPV6_JOIN_GROUP, MCAST_JOIN_GROUP, MCAST_JOIN_SOURCE_ GROUP | The specified multicast address and interface address (or interface index) pair is already in use. | Correct the specified multicast address, interface address, or interface index.
49 | EADDRNOTAVAIL | Bind | The specified address is incorrect for this host. | Correct the function address parameter.
49 | EADDRNOTAVAIL | Connect | The calling host cannot reach the specified destination. | Correct the function address parameter.
49 | EADDRNOTAVAIL | Multicast APIs | The specified multicast address, interface address, or interface index is not correct. | Correct the specified address.
49 | EADDRNOTAVAIL | IP_BLOCK_SOURCE, IP_ADD_SOURCE_ MEMBERSHIP, MCAST_BLOCK_SOURCE, MCAST_JOIN_SOURCE_ GROUP | A duplicate source IP address is specified on the multicast group and interface pair. | Correct the specified source IP address.
49 | EADDRNOTAVAIL | IP_UNBLOCK_SOURCE, IP_DROP_SOURCE_ MEMBERSHIP, MCAST_UNBLOCK_ SOURCE, MCAST_LEAVE_SOURCE_ GROUP | A previously blocked source multicast group cannot be found. | Correct the specified address.
50 | ENETDOWN | All | The network is down. | Retry when the connection path is up.
51 | ENETUNREACH | Connect | The network cannot be reached. | Ensure that the target application is active.
52 | ENETRESET | All | The network dropped a connection on a reset. | Reestablish the connection between the applications.
53 | ECONNABORTED | All | The software caused a connection abend. | Reestablish the connection between the applications.
54 | ECONNRESET | All | The connection to the destination host is not available. | N/A
54 | ECONNRESET | Send Write | The connection to the destination host is not available. | The socket is closing. Issue Send() or Write() before closing the socket.
55 | ENOBUFS | All | No buffer space is available. | Check the application for massive storage allocation call.
55 | ENOBUFS | Accept | Not enough buffer space is available to create the new socket. | Call your system administrator.
55 | ENOBUFS | Send Sendto Write | Not enough buffer space is available to send the new message. | Call your system administrator.
55 | ENOBUFS | IOCTL (SIOCTTLSCTL TTLS_Version1 requesting TTLS_RETURN_ CERTIFICATE or TTLS_Version2 query) | The buffer size provided is too small. | For TTLS_Version1 use the returned certificate length to allocate a larger buffer and reissue IOCTL with the larger buffer.
55 | ENOBUFS | Takesocket | Not enough buffer space is available to create the new socket. | Call your system administrator.
55 | ENOBUFS | IOCTL (SIOCSAPPLDATA) | There is no storage available to store the associated data. | Call your system administrator.
55 | ENOBUFS | IP_BLOCK_SOURCE, IP_ADD_SOURCE_ MEMBERSHIP, MCAST_BLOCK_SOURCE, MCAST_JOIN_SOURCE_ GROUP, SIOCSIPMSFILTER, SIOCSMSFILTER, setipv4sourcefilter, setsourcefilter | A maximum of 64 source filters can be specified per multicast address, interface address pair. | Remove unneeded source IP addresses and reenter the command.
56 | EISCONN | Connect | The socket is already connected. | Correct the socket descriptor on Connect() or do not issue a Connect() twice for the socket.
57 | ENOTCONN | All | The socket is not connected. | Connect the socket before communicating.
57 | ENOTCONN | IOCTL (SIOCTTLSCTL) | The socket is not connected. | Issue the SIOCTTLSCTL IOCTL only after the socket is connected.
58 | ESHUTDOWN | All | A Send cannot be processed after socket shutdown. | Issue read/receive before shutting down the read side of the socket.
59 | ETOOMANYREFS | All | There are too many references. A splice cannot be completed. | Call your system administrator.
59 | ETOOMANYREFS | IP_ADD_MEMBERSHIP, IP_ADD_SOURCE_ MEMBERSHIP, MCAST_JOIN_GROUP, MCAST_JOIN_SOURCE_ GROUP, IPV6_JOIN_GROUP | A maximum of 20 multicast groups per single UDP socket or a maximum of 256 multicast groups per single RAW socket can be specified. | Remove unneeded multicast groups and reenter the command.
60 | ETIMEDOUT | Connect | The connection timed out before it was completed. | Ensure the server application is available.
61 | ECONNREFUSED | Connect | The requested connection was refused. | Ensure server application is available and at specified port.
62 | ELOOP | All | There are too many symbolic loop levels. | Reduce symbolic links to specified file.
63 | ENAMETOOLONG | All | The file name is too long. | Reduce size of specified file name.
64 | EHOSTDOWN | All | The host is down. | Restart specified host.
65 | EHOSTUNREACH | All | There is no route to the host. | Set up network path to specified host and verify that host name is valid.
66 | ENOTEMPTY | All | The directory is not empty. | Clear out specified directory and reissue call.
67 | EPROCLIM | All | There are too many processes in the system. | Decrease the number of processes or increase the process limit.
68 | EUSERS | All | There are too many users on the system. | Decrease the number of users or increase the user limit.
69 | EDQUOT | All | The disk quota has been exceeded. | Call your system administrator.
70 | ESTALE | All | An old NFS** data set handle was found. | Call your system administrator.
71 | EREMOTE | All | There are too many levels of remote in the path. | Call your system administrator.
72 | ENOSTR | All | The device is not a stream device. | Call your system administrator.
73 | ETIME | All | The timer has expired. | Increase timer values or reissue function.
74 | ENOSR | All | There are no more stream resources. | Call your system administrator.
75 | ENOMSG | All | There is no message of the desired type. | Call your system administrator.
76 | EBADMSG | All | The system cannot read the message. | Verify that z/OS Communications Server installation was successful and that message files were properly loaded.
77 | EIDRM | All | The identifier has been removed. | Call your system administrator.
78 | EDEADLK | All | A deadlock condition has occurred. | Call your system administrator.
78 | EDEADLK | Select Selectex | None of the sockets in the socket descriptor sets are either AF_INET or AF_IUCV sockets and there is no timeout value or no ECB specified. The select/selectex would never complete. | Correct the socket descriptor sets so that an AF_INET or AF_IUCV socket is specified. A timeout or ECB value can also be added to avoid the select/selectex from waiting indefinitely.
79 | ENOLCK | All | No record locks are available. | Call your system administrator.
80 | ENONET | All | The requested machine is not on the network. | Call your system administrator.
81 | ERREMOTE | All | The object is remote. | Call your system administrator.
82 | ENOLINK | All | The link has been severed. | Release the sockets and reinitialize the client-server connection.
83 | EADV | All | An ADVERTISE error has occurred. | Call your system administrator.
84 | ESRMNT | All | An SRMOUNT error has occurred. | Call your system administrator.
85 | ECOMM | All | A communication error has occurred on a Send call. | Call your system administrator.
86 | EPROTO | All | A protocol error has occurred. | Call your system administrator.
86 EPROTO IOCTL (SIOCTTLSCTL requesting TTLS_RESET_ SESSION, TTLS_RESET_ CIPHER, TTLS_STOP_ CONNECTION, or TTLS_ALLOW_ HSTIMEOUT) One of the following errors occurred:
  • A TTLS_INIT_ CONNECTION request has not been received for the connection
  • TTLS_RESET_ CIPHER or TTLS_STOP_ CIPHER was requested on a connection that is secured using SSL version 2.
  • TTLS_ALLOW_ HSTIMEOUT was requested but the policy has the HandshakeRole value client or the HandshakeTimeout is 0.
Request TTLS_INIT_ CONNECTION prior to requesting TTLS_RESET_SESSION or TTLS_RESET_CIPHER. Request TTLS_RESET_CIPHER or TTLS_STOP_ CONNECTION only on connections secured using SSL version 3 or TLS version 1. Request TTLS_ALLOW_ HSTIMEOUT only when the security type is TTLS_SEC_SERVER or higher and the HandshakeTimeout is not 0.
87 | EMULTIHOP | All | A multihop address link was attempted. | Call your system administrator.
88 | EDOTDOT | All | A cross-mount point was detected. This is not an error. | Call your system administrator.
89 | EREMCHG | All | The remote address has changed. | Call your system administrator.
90 | ECONNCLOSED | All | The connection was closed by a peer. | Check that the peer is running.
113 | EBADF | All | Socket descriptor is not in correct range. The maximum number of socket descriptors is set by MAXDESC(). The default range is 0-49. | Reissue function with corrected socket descriptor.
113 | EBADF | Bind socket | The socket descriptor is already being used. | Correct the socket descriptor.
113 | EBADF | Givesocket | The socket has already been given. The socket domain is not AF_INET. | Correct the socket descriptor.
113 | EBADF | Select | One of the specified descriptor sets is an incorrect socket descriptor. | Correct the socket descriptor. Set on Select() or Selectex().
113 | EBADF | Takesocket | The socket has already been taken. | Correct the socket descriptor.
113 | EBADF | Accept | A Listen() has not been issued before the Accept(). | Issue Listen() before Accept().
121 | EINVAL | All | An incorrect argument was specified. | Check and correct all function parameters.
121 EINVAL IOCTL (SIOCSAPPLDATA) The input parameter is not a correctly formatted SetApplData structure.
  • The SetAD_eye1 value is not valid.
  • The SetAD_ver value is not valid.
  • The storage pointed to by SetAD_ptr does not contain a correctly formatted SetADcontainer structure.
  • The SetAD_eye2 value is not valid.
  • The SetAD_len value contains an incorrect length for the SetAD_ver version of the SetADcontainer structure.
Check and correct all function parameters.
122 | ECLOSED
126 | ENMELONG
136 | ENOTEMPT
145 | E2BIG | All | The argument list is too long. | Eliminate excessive number of arguments.
156 EMVSINITIAL All Process initialization error.

This indicates an z/OS® UNIX® process initialization failure. This is usually an indication that a proper OMVS RACF® segment is not defined for the user ID associated with application. The RACF OMVS segment may not be defined or may contain errors such as an improper HOME() directory specification.

Attempt to initialize again. After ensuring that an OMVS Segment is defined, if the errno is still returned, call your MVS™ system programmer to have IBM® service contacted.
157 | EMISSED
1002 | EIBMSOCKOUTOFRANGE | Socket | A socket number assigned by the client interface code is out of range. | Check the socket descriptor parameter.
1003 | EIBMSOCKINUSE | Socket | A socket number assigned by the client interface code is already in use. | Use a different socket descriptor.
1004 | EIBMIUCVERR | All | The request failed because of an IUCV error. This error is generated by the client stub code. | Ensure IUCV/VMCF is functional.
1008 | EIBMCONFLICT | All | This request conflicts with a request already queued on the same socket. | Cancel the existing call or wait for its completion before reissuing this call.
1009 | EIBMCANCELLED | All | The request was canceled by the CANCEL call. | Informational, no action needed.
1011 | EIBMBADTCPNAME | All | A TCP/IP name that is not valid was detected. | Correct the name specified in the IBM_TCPIMAGE structure.
1011 | EIBMBADTCPNAME | Setibmopt | A TCP/IP name that is not valid was detected. | Correct the name specified in the IBM_TCPIMAGE structure.
1011 | EIBMBADTCPNAME | INITAPI | A TCP/IP name that is not valid was detected. | Correct the name specified on the IDENT option TCPNAME field.
1012 | EIBMBADREQUESTCODE | All | A request code that is not valid was detected. | Contact your system administrator.
1013 | EIBMBADCONNECTIONSTATE | All | A connection token that is not valid was detected; bad state. | Verify TCP/IP is active.
1014 | EIBMUNAUTHORIZEDCALLER | All | An unauthorized caller specified an authorized keyword. | Ensure user ID has authority for the specified operation.
1015 | EIBMBADCONNECTIONMATCH | All | A connection token that is not valid was detected. There is no such connection. | Verify TCP/IP is active.
1016 | EIBMTCPABEND | All | An abend occurred when TCP/IP was processing this request. | Verify that TCP/IP has restarted.
1023 | EIBMTERMERROR | All | Encountered a terminating error while processing. | Call your system administrator.
1026 | EIBMINVDELETE | All | Delete requestor did not create the connection. | Delete the request from the process that created it.
1027 | EIBMINVSOCKET | All | A connection token that is not valid was detected. No such socket exists. | Call your system programmer.
1028 | EIBMINVTCPCONNECTION | All | Connection terminated by TCP/IP. The token was invalidated by TCP/IP. | Reestablish the connection to TCP/IP.
1032 | EIBMCALLINPROGRESS | All | Another call was already in progress. | Reissue after previous call has completed.
1036 | EIBMNOACTIVETCP | All | TCP/IP is not installed or not active. | Correct TCP/IP name used.
1036 | EIBMNOACTIVETCP | Select | EIBMNOACTIVETCP | Ensure TCP/IP is active.
1036 | EIBMNOACTIVETCP | Getibmopt | No TCP/IP image was found. | Ensure TCP/IP is active.
1037 | EIBMINVTSRBUSERDATA | All | The request control block contained data that is not valid. | Call your system programmer.
1038 | EIBMINVUSERDATA | All | The request control block contained user data that is not valid. | Check your function parameters and call your system programmer.
1040 | EIBMSELECTEXPOST | SELECTEX | SELECTEX passed an ECB that was already posted. | Check whether the user's ECB was already posted.
1112 | ECANCEL
2001 | EINVALIDRXSOCKETCALL | REXX™ | A syntax error occurred in the RXSOCKET parameter list. | Correct the parameter list passed to the REXX socket call.
2002 | ECONSOLEINTERRUPT | REXX | A console interrupt occurred. | Retry the task.
2003 | ESUBTASKINVALID | REXX | The subtask ID is incorrect. | Correct the subtask ID on the INITIALIZE call.
2004 | ESUBTASKALREADYACTIVE | REXX | The subtask is already active. | Only issue the INITIALIZE call once in your program.
2005 | ESUBTASKALNOTACTIVE | REXX | The subtask is not active. | Issue the INITIALIZE call before any other socket call.
2006 | ESOCKNETNOTALLOCATED | REXX | The specified socket could not be allocated. | Increase the user storage allocation for this job.
2007 | EMAXSOCKETSREACHED | REXX | The maximum number of sockets has been reached. | Increase the number of allocate sockets, or decrease the number of sockets used by your program.
2009 | ESOCKETNOTDEFINED | REXX | The socket is not defined. | Issue the SOCKET call before the call that fails.
2011 | EDOMAINSERVERFAILURE | REXX | A Domain Name Server failure occurred. | Call your MVS system programmer.
2012 | EINVALIDNAME | REXX | An incorrect name was received from the TCP/IP server. | Call your MVS system programmer.
2013 | EINVALIDCLIENTID | REXX | An incorrect clientid was received from the TCP/IP server. | Call your MVS system programmer.
2014 | ENIVALIDFILENAME | REXX | An error occurred during NUCEXT processing. | Specify the correct translation table file name, or verify that the translation table is valid.
2016 | EHOSTNOTFOUND | REXX | The host is not found. | Call your MVS system programmer.
2017 | EIPADDRNOTFOUND | REXX | Address not found. | Call your MVS system programmer.
3412 | ENODATA | Message does not exist.
3416 | ELINKED | Stream is linked.
3419 | ERECURSE | Recursive attempt rejected.
3420 | EASYNC | Asynchronous I/O scheduled. This is a normal, internal event that is NOT returned to the user.
3448 | EUNATCH | The protocol required to support the specified address family is not available.
3464 | ETERM | Operation terminated.
3474 | EUNKNOWN | Unknown system state.
3495 | EBADOBJ | You attempted to reference a object that does not exist.
3513 | EOUTOFSTATE | Protocol engine has received a command that is not acceptable in its current state.
Parent topic: Configuring and Managing EZASOKET Support for CICS Applications


Working with Mainframe Files

Enterprise Developer provides functionality that you can use to work with files and data located on the mainframe. This section describes the functionality.

You can also configure an SNA server and set up links between CICS regions running in an Enterprise Server environment, and CICS regions running on a mainframe. This functionality is covered in a different area of the help.

  • About Enterprise Server and Mainframe Access
  • Configuring and Administering the Mainframe
  • Using Enterprise Server with a Mainframe
Parent topic: Micro Focus Enterprise Server 2.3 Update 1 for Windows
Related concepts
Setting Up Communications with Mainframe CICS Regions


About Enterprise Server and Mainframe Access

Enterprise Server provides the following components that allow you to work with programs and data on a mainframe:

  • The Automatic Synchronize and Compile (ASC) utility enables users to automatically synchronize components on the PC with components on the mainframe
  • Drag and Drop allows you to transfer files easily between mainframe and PC environments. It provides a simple drag and drop user interface to do this.
  • Compare and Synchronization Monitor allows you to synchronize mainframe and PC versions of files. For example, changes made to PC-environment files can be configured to synchronize with corresponding files in the mainframe environment, and vice versa.
  • Mainframe Call Generator allows you to set up application to mainframe calls.
  • The Remote Job Step Execution (RJSE) facility enables execution of one or more steps of a job on a remote z/OS host
  • SourceConnect allows you to map a mainframe environment to a PC drive. With SourceConnect for example, you can use applications running in a PC environment to access resources on a mainframe.
Parent topic: Working with Mainframe Files


Configuring and Administering the Mainframe

This section describes how to configure and administer a Mainframe Access installation's mainframe components.

Mainframe Access is middleware that runs on OS/390 and z/OS mainframes and provides access to mainframe resources for Micro Focus client products.

This help is for mainframe system administrators who are responsible for configuring and running Mainframe Access. You should be familiar with z/OS system definitions and the TSO-ISPF interface.

  • Mainframe Access Overview
  • Configuration
  • Administration Using Console Commands
  • Troubleshooting
  • Customizing Data Connect
  • Configuring Access to External Library Management Systems
  • Configuring Access to Enterprise Server Mainframe Subsystem Support
  • Configuring the Enterprise Server Environment
  • Mainframe Access Messages
Parent topic: Working with Mainframe Files


Mainframe Access Overview

Mainframe Access is the OS/390 and z/OS server for Micro Focus development environments. It is a common component providing access to host resources for environments. One installation of Mainframe Access can support all of these products, providing connectivity to any number of DB2, IMS, and CICS systems located anywhere in an enterprise. It can also provide access to JES facilities, VSAM data sets, non-VSAM data sets, and data controlled by external library management products such as Panvalet, Librarian and Endevor.

Note: Mainframe Access is supported on z/OS and OS/390 environments. Unless specifically stated otherwise, references to z/OS also apply to OS/390.

Mainframe Access is data and transaction middleware that exploits the best features of workgroup and enterprise architectures. Micro Focus client programs can achieve the same performance levels, security, and data integrity that native mainframe applications deliver. The technology requires no changes to existing mainframe security, database, and transaction processing systems.

Mainframe Access provides access to:

  • DB2 for z/OS and OS/390 from clients
  • CICS transactions and data from clients
  • IMS data from clients via the Remote IMS Server
  • Non-relational data sets (VSAM, sequential, partitioned, etc.) from Mainframe Access Client
  • Mainframe source control systems the Mainframe Access Client
  • JES2 and JES3 from the Mainframe Access Client

The figure below illustrates the relationships between Mainframe Access, its client systems and the z/OS services it provides.

Figure 1. Mainframe Access Architecture
Mainframe Access Architecture
  • Communications
  • Security
  • Data Set Services
  • Administration
  • Dependent Address Space Services
  • Mainframe Access Services
Parent topic: Configuring and Administering the Mainframe


Communications

Mainframe Access provides comprehensive support for communications between PC clients and mainframe servers. Mainframe Access supports both TCP/IP and LU6.2 protocols. Mainframe Access' ability to bridge client TCP/IP connections to SNA LU6.2 server connections eliminates the need to install, configure and maintain SNA software packages on your client and server workstations. You can even access any DB2 for z/OS and OS/390 database using TCP/IP client connections, without the need for specific levels of DB2 software. Normally, DB2 Version 5.1, or later, is required for TCP/IP access. Mainframe Access, however, dynamically associates TCP/IP client connections with traditional LU6.2 DRDA connections to the DB2 systems.

Details are as follows:

  • TCP/IP Communications

    Mainframe Access has two TCP/IP socket listeners, one for TCP/IP clients using proprietary protocols and one for HTTP clients. The listeners accept client connection requests and examine the request data to determine the target server or internal destination for the request. When the target server is external, the client connection is then associated with an LU6.2 connection to the target server. For each target server type, Mainframe Access creates an initial number of tasks (z/OS TCBs) to handle the client/server connection association and processing. As each connection request arrives, Mainframe Access scans all available tasks for the target server and assigns the new connection request to the task with the lightest load. Mainframe Access' TCP/IP communications support can be used with IBM's z/OS TCP/IP implementation.

  • LU6.2 Communications

    When the first client request for an LU6.2 target server is received, Mainframe Access establishes the LU6.2 connection to the target server and negotiates session limits for the mode name associated with conversations (user transactions) to the target server. Mainframe Access then prepares an LU6.2 Function Management Header 5 (FMH-5) and allocates a conversation to the target server. The FMH-5 includes any LU6.2 security subfields (user ID and password) provided by the client and an LUW ID (SNA Logical Unit of Work ID) generated by Mainframe Access to manage the unit of work. Packaged user data to be processed by the transaction program follows the FMH-5. Acceptance of the conversation request by the target server starts the execution of the remote transaction program that will process the request. Response data from the remote transaction program is received by Mainframe Access and returned to the requesting client through the TCP/IP connection. If an LU6.2 communications error occurs during the request processing, Mainframe Access creates a special packet containing the LU6.2 error information and returns this to the requesting client.

Parent topic: Mainframe Access Overview


Security

Mainframe Access provides security features that interact with existing mainframe, operating system, and software security schemes. They are:

  • System Authorization Facility (SAF) interface

    Mainframe Access' security component uses the z/OS SAF interface to verify the user IDs and passwords and to check the authorization of users to access and update z/OS data sets. The Password Expiration Manager (PEM) feature of Mainframe Access is used by some client products; PEM allows PC end users to change their mainframe password using the SAF interface. Mainframe Access uses the SAF RACROUTE interface, and therefore exploits the existing security definitions in your external security manager, such as IBM's RACF, CA-ACF-2, and CA-Top Secret.

  • Encryption

    Mainframe Access and its associated products use several methods of encryption and encoding, including 32-bit private key algorithms, to manage the encryption and decryption of passwords and data.

  • Access List Checking

    You can use this optional feature to restrict client connections based on the IP address of the incoming client. You create an access list that specifies which client IP addresses, or ranges of addresses, are allowed or disallowed. Once you have enabled access list checking, Mainframe Access always validates the incoming client's IP address using your specifications and rejects unauthorized connection attempts.

  • Audit Logging

    Mainframe Access' optional audit logging facility records client login and logout information to a VSAM file. The information that is recorded includes user ID, login and logout times, target server, security status, and other data.

Parent topic: Mainframe Access Overview


Data Set Services

Mainframe Access' Data Set Services component uses state-of-the-art z/OS data management interfaces and facilities to provide file services for z/OS data sets. Data Set Services is designed to support the data access and security requirements of VSAM and non-VSAM data sets in a high-performance, multi-user environment.

Parent topic: Mainframe Access Overview


Administration

Mainframe Access provides functions to monitor and control the processing of work, for example:

  • Client Timeout Management

    Mainframe Access monitors the activity of clients that have a persistent connection to Mainframe Access for activity and disconnects them from the system after a length of idle time that you specify. It also releases all of the associated client resources on the mainframe, including LU6.2 conversations with server systems.

  • Trace Facility

    The tracing facility of Mainframe Access traces both the client flow (usually TCP/IP) and server flow (usually LU6.2) simultaneously, recording all control information and data to a single output destination. The trace information is very useful for diagnosing client/server communication problems. You can turn tracing on and off dynamically while Mainframe Access is running.

Mainframe Access provides a set of simple commands that you can use to monitor and control its run-time operations. You can use the commands from an z/OS console or from a Telnet client; for further information see the chapter Administration Using Console Commands.

You can use Mainframe Access' administrative interfaces to obtain comprehensive displays of current system activity and internal components of the system. The information provided extends from overall systems operation down to details about individual client/server connections. You can update important operational definitions and functions of the system, such as target server parameters, idle timeout value, access list specifications and trace activity while the system is running.

Parent topic: Mainframe Access Overview
Related information
Administration Using Console Commands


Dependent Address Space Services

Mainframe Access' Dependent Address Space Services component uses standard z/OS facilities to create and manage auxiliary Application Server address spaces for program execution. This feature is used to automatically start a Mainframe Access Data Connect server address space during Mainframe Access initialization. The Data Connect server is also stopped automatically during Mainframe Access shutdown.

Parent topic: Mainframe Access Overview


Mainframe Access Services

Mainframe Access Drag & Drop and Source Connect functions are seamlessly integrated into the overall server workload. Mainframe Access' high-performance task, communications, transaction and data set management services are leveraged to increase the speed, reliability and scalability for these functions.

Parent topic: Mainframe Access Overview


Configuration

This chapter describes how to configure Mainframe Access and verify that it is correctly installed and configured and is ready to run.

  • Configuration Overview
  • Installing and Configuring Mainframe Libraries
  • Quick Configuration
  • Advanced Configuration Activities
  • Running Multiple Instances of Mainframe Access Server
Parent topic: Configuring and Administering the Mainframe


Configuration Overview

There are two types of configuration tasks that you must complete before you can start and use Mainframe Access. These are:

  • Updating the z/OS mainframe system to create an execution environment for Mainframe Access
  • Setting parameters to meet your requirements

The process of configuring Mainframe Access is separated into two distinct procedures; Quick Configuration and Advanced Configuration Activities.

Quick configuration is performed using the UpQuick instructions as indicated during the CD installation process. These configuration steps must be completed for all installations. Quick configuration takes care of all of the z/OS customizations and many basic Mainframe Access customizations. This quick configuration is the only mainframe Mainframe Access setup required for Mainframe Access Drag and Drop, SQL Option for DB2, and basic Mainframe Access Data Connect server functions.

Additional setup is required if you will be using Mainframe Access Data Connect server and you need to use the file name mapping table and/or alter the processing in the SAF security exits. Additional setup is also required if you will be using Remote IMS, ES/MSS support, Mainframe Access's access list checking, Mainframe Access's audit log, and/or Mainframe Access's support for external library management systems. The section on advanced configuration describes these additional customizations.

If you have completed the installation process, including the UpQuick configuration steps, and if you are not going to use features that require additional setup, your configuration is complete.

If you have uploaded and restored the Mainframe Access data sets but you have not completed the UpQuick configuration, you should begin with Quick Configuration.

If you have completed the configuration and testing of your basic Mainframe Access server and you need to customize for an advanced feature, you should continue at Advanced Configuration Activities.

  • Mainframe Access Data Sets
  • Mainframe Access Samples
Parent topic: Configuration


Mainframe Access Data Sets

Following the instructions on the CD, you should have already completed the upload and restore of the Mainframe Access data sets. During that process you selected a high level qualifier to be used for all of your Mainframe Access data sets. This guide refers to the qualifier that you selected as <hlq> or hlq. The data sets that you restored are listed in the following table.

DATA SET | DESCRIPTION
<hlq>.CNTL | Samples for Mainframe Access server. These include JCL for jobs to be run, JCL for started task procedures and parameter files. The members in this data set are referred to frequently in these configuration instructions.
<hlq>.LOADLIB | The load module library for Mainframe Access server. This library must be APF-authorized.
<hlq>.MFAVCTL | A pre-allocated library for Mainframe Access Data Connect server dynamic allocation control file members. This data set is allocated during installation but no members are restored into it. You may use this data set during customization for the Data Connect feature.
<hlq>.RIMS | All of the product source and object files that you may need during setup of the Remote IMS Server feature.
<hlq>.TABLES | Translation tables used by Mainframe Access server.
Parent topic: Configuration Overview


Mainframe Access Samples

The installation procedure places many samples in the <hlq>.CNTL data set. If a sample is provided for a configuration task, use it as a starting point for your configuration. Usually you need to edit the sample, replacing provided information with information that is unique to your system.

The following table summarizes the samples that are provided for Mainframe Access.

MEMBER | DESCRIPTION
ACCESS | List used to restrict access to Mainframe Access consisting of the IP addresses of connecting clients. The access list also contains the list of user IDs that are authorized to access the Mainframe Access administration functions through the Web browser interface. You should add the IP addresses and user IDs for your system; see the section Editing Access List Definitions.
AUDIT | JCL for creating and initializing a Mainframe Access audit log data set. The audit log is a VSAM key sequenced data set (KSDS). You should edit the sample to include JOB card information, data set names and a volume serial number.
AUDRPT | JCL for running the Mainframe Access audit log report program to list the contents of the audit log data set. You should edit the sample to include JOB card information and data set names.
FRESTORE | A copy of the FRESTORE job for reference purposes. This job was originally transferred from CD to the <hlq>.UPLOAD data set during installation. The job was customized and submitted to allocate the permanent Mainframe Access data sets and restore the data set content from other uploaded files.
GTFCNTL | Input control statements referenced by the sample JCL procedure in member MFAGTF.
INSTALL | A copy of the installation upload instructions for reference purposes. These are the instructions that describe how to allocate the <hlq>.UPLOAD data set and transfer the CD content into that data set.
MFA | JCL for executing Mainframe Access. You should edit the sample to include your data set names. This JCL contains references to the ACCESS, PARMS and SERVERS sample members.
MFAAS | JCL for executing a Mainframe Access Application Server. Application servers are auxiliary address spaces that process specific types of client requests such as Endevor transactions. You should edit the sample to include your data set names. This JCL contains a reference to the PARMSAS sample member.
MFAGTF | JCL for running IBM's Generalized Trace Facility (GTF). GTF provides high-performance recording of diagnostic data and can be useful during problem determination. You should edit the sample to include your data set names.
MFANLS | JCL for re-compiling the default code page that may be configured at a client workstation. This is equivalent to the MFLSCTRN load module of Mainframe Access Version 2. During installation the default is set to use code pages E037/A437 for EBCDIC/ASCII translation. The sample JCL contains instructions for changing the default code pages selected by installation.
MFAS | JCL for executing the Mainframe Access Data Connect server. You should edit the sample to include your data set names.
MFAVTAM | Definition of VTAM applications for Mainframe Access, Mainframe Access Data Connect, ES/MSS and Remote IMS Server. You can edit the sample to include your own ACB names and network names (see the section VTAMLST Definitions).
PARMS | Parameters that are read when Mainframe Access is initialized. The sample JCL for executing Mainframe Access refers to this member for parameter input. You will need to edit some of these parameters. For full details see the section Editing Mainframe Access Parameters .
PARMSAS | Parameters that are read when a Mainframe Access Application Server address space initializes. The sample JCL MFAAS, for executing a Mainframe Access Application Server, refers to this member for parameter input. You will need to edit some of these parameters. For full details see the section Editing Mainframe Access Parameters .
PVSUFFX | JCL for executing a migration tool which extracts a text definition from the MFLSCPAN load module of Mainframe Access Version 2. For full details see the section Panvalet in Appendix C.
SERVERS | Definitions that describe the z/OS subsystems that will be providing service in response to client requests. The servers are your IMS and CICS subsystems, the Mainframe Access Data Connect server and ES/MSS servers. You must edit the sample to include information specific to your servers and also coordinate the information with definitions in the client packages.
TSOXMIT | Sample job that uses TSO XMIT to package diagnostic data for transmission.
UPQUICK | A copy of the quick configuration instructions for reference purposes. These are the instructions that describe how to quickly configure z/OS and Mainframe Access to create an operational Mainframe Access server system. These same instructions are reiterated in the Quick Configuration section.
Parent topic: Configuration Overview
Related information
Editing Access List Definitions
VTAMLST Definitions
Editing Mainframe Access Parameters
Panvalet
Quick Configuration


Installing and Configuring Mainframe Libraries

The z/OS libraries for Mainframe Access, Mainframe Access Data Connect and the Remote IMS Server are stored on the CD in a compressed format. Follow the upload instructions on the CD to transfer the compressed files up to a mainframe partitioned data set and then run the restore job to expand all of the compressed files into proper z/OS data sets. All of the product data sets for Mainframe Access, Mainframe Access Data Connect and Remote IMS Server will then be ready to use.

The upload instructions refer you to the UpQuick instructions for Mainframe Access. This file is contained in one of the restored mainframe data sets. Follow the UpQuick instructions to complete the basic customization of z/OS and product parameters for Mainframe Access and Mainframe Access Data Connect. Upon completion of the UpQuick procedure you will be able to start Mainframe Access (Mainframe Access Data Connect will be automatically started as part of Mainframe Access initialization) and validate the successful installation of the software. This quick configuration is the only Mainframe Access setup required for Drag and Drop, SQL Option for DB2, and basic Mainframe Access Data Connect functions.

The additional setup required for Mainframe Access' access list checking, audit log, and/or external library management system interfaces is described in the chapter Configuration.

If you will be using Remote IMS or Mainframe Subsystem Support, there are Mainframe Access parameters that you must configure to define and activate these features. . Some of the Mainframe Access configuration information must be coordinated with the client configuration for these features.

Note:
  • Mainframe Access is not supplied in SMP/E format.
Parent topic: Configuration


Quick Configuration

After you have uploaded the mainframe files and successfully run the FRESTORE job, there are some basic customization tasks that must be completed. Quick configuration works through these configuration tasks quickly and gets you to the point where the software can be started and a basic installation verification check can be performed. After the installation verification check, continue with Advanced Configuration Activities if there are additional features that you need to set up.

You should be familiar with TSO, ISPF, SDSF, z/OS system commands, JCL procedures and proclibs, VTAMLST definitions and RACF.

Note:

These instructions refer to RACF as the security subsystem. Mainframe Access does use the SAF interface to the security subsystem and is compatible with other security products that provide the SAF API. When these instructions refer to RACF-related customizations, please refer to your security product documentation to determine the corresponding security subsystem changes.

If you are using the ISPF editor to make the configuration changes, use the change command once to make the first update to the hlq value and then use ISPF's Rchange command (usually PF6) to apply the same change in all the members that you need to update. For example: use "c HLQ MY.HIGH.LEVEL" the first time and then PF6 to apply the same change in other places. Changes to other parameters are easily accomplished by overtyping the preset value.

  • Before You Begin
  • MFA Started Task JCL Procedure
  • MFAAS Started Task JCL Procedure
  • MFAS Started Task JCL Procedure
  • Mainframe Access PARMS
  • VTAMLST Definitions
  • Add Started Task JCL Procedures to a Proclib
  • APF-Authorize the Load Module Libraries
  • Define Mainframe Access to the Security Subsystem
  • Starting Mainframe Access
  • Stopping Mainframe Access
Parent topic: Configuration
Related concepts
Prerequisites
Advanced Configuration Activities
Related information
Advanced Configuration Activities


Before You Begin

The following table lists important configuration data that you will need to know in order to complete the quick configuration. Review these items and determine the appropriate values before you proceed with customization.

ITEM | DESCRIPTION
userid | TSO user ID that can update proclib , update vtamlst , update RACF, and issue z/OS system commands through SDSF. Alternatively, the cooperation of individuals with the appropriate authorities.
hlq | High level qualifier that was given to all Mainframe Access data sets when the FRESTORE job was run.
clientport | A TCP/IP port number on the mainframe that you will reserve for Mainframe Access and client connections.
stcuserid | RACF user ID that you want to associate with the Mainframe Access started tasks
stcgroup | RACF group ID that you want to associate with the Mainframe Access started tasks.
tcpdata | Data set name of the IBM TCP/IP "TCPIP.DATA" data set that provides configuration information to programs that use TCP/IP.
proclib | Data set name of a system procedure library.
vtamlst | Data set name of the active VTAMLST definitions data set.
netid | VTAM SNA network id used on your system. See NETID= in the active ATCSTRxx vtamlst member.
loadvolser | DASD volume serial number of the volume containing the Mainframe Access load module libraries. FRESTORE allocated and built these libraries.
Parent topic: Quick Configuration


MFA Started Task JCL Procedure

Customize member MFA in the CNTL data set. This is the started task JCL procedure for Mainframe Access server. Use the ISPF change command to change HLQ to your qualifier ( hlq ).

If you are using IBM's TCP/IP, overtype TCPIP.OS390.TCPDATA with the name of your installation's "TCPIP.DATA" data set ( tcpdata ). This is the data set used by client programs to obtain the name of the TCP/IP started task and other installation-dependent TCP/IP information.

To enable DBCS support, you need to edit the procedure by uncommenting the following four statements:
//*---------------------------------------------------
//* Optional DBCS code pages
//*---------------------------------------------------
//*
//*EZACHLAT DD  DSN=TCPIP.SEZADBCX(EZACHLAT),DISP=SHR
//*EZAHGLAT DD  DSN=TCPIP.SEZADBCX(EZAHGLAT),DISP=SHR
//*EZAKJLAT DD  DSN=TCPIP.SEZADBCX(EZAKJLAT),DISP=SHR
//*EZASCLAT DD  DSN=TCPIP.SEZADBCX(EZASCLAT),DISP=SHR
Parent topic: Quick Configuration


MFAAS Started Task JCL Procedure

Customize member MFAAS in the CNTL data set. This is the started task JCL procedure for Mainframe Access Application Servers. Use the ISPF change command to change HLQ to your qualifier ( hlq ).

If you are using IBM's TCP/IP, overtype TCPIP.OS390.TCPDATA with the name of your installation's "TCPIP.DATA" data set ( tcpdata ).

Parent topic: Quick Configuration


MFAS Started Task JCL Procedure

Customize member MFAS in the CNTL data set. This is the started task JCL procedure for Mainframe Access Data Connect server. Use the ISPF Rchange command to change HLQ to your qualifier ( hlq ).

Parent topic: Quick Configuration


Mainframe Access PARMS

Customize member PARMS in the CNTL data set. These are the Mainframe Access server initialization parameters referenced by the Mainframe Access started task JCL.

Change TCP_PORT=2020 to TCP_PORT= clientport . This is the port number that Micro Focus client software should be configured to use.

Change NETWORK ID=DDINET1 to NETWORK ID= netid , the VTAM SNA network id of your system.

Parent topic: Quick Configuration


VTAMLST Definitions

Copy member MFAVTAM to vtamlst . This application major node definition contains APPL definitions for Mainframe Access server, Mainframe Access Data Connect server and Remote IMS Server. Use the z/OS VARY command to activate the definition:

V NET,ACT,ID=MFAVTAM
Note:
  • If you change any ACBNAME= values or the PRTCT= value in the MFAVTAM sample you must make corresponding changes:
    • in member PARMS (if ACBNAME=MFM62ACB is changed)
    • in member PARMS (if PRTCT=MFM62PSW is changed)
    • in member SERVERS (if ACBNAME=MFA62ACB is changed)
    • in member MFAS (if ACBNAME=MFA62ACB is changed)
    • in member SERVERS (if ACBNAME=MFAMTO1 is changed)
    • in member SERVERS (if ACBNAME=MFAMTO2 is changed)
  • You will want to add MFAVTAM into the vtamlst (ATCCONxx) member so that this application major node is automatically activated during VTAM initialization.
Parent topic: Quick Configuration


Add Started Task JCL Procedures to a Proclib

Copy members MFA, MFAAS and MFAS to proclib .

Note:
  • If you store proc MFAS in proclib using a different name, you must also change ASPROC=MFAS in member SERVERS to specify that new proc name.
  • If you store proc MFAAS in proclib using a different name, you must also change ASPROC=MFAAS in member SERVERS to specify that new proc name.
Parent topic: Quick Configuration


APF-Authorize the Load Module Libraries

Use z/OS SETPROG commands to APF-authorize the load libraries:

SETPROG APF,ADD,DSNAME=hlq.LOADLIB,VOLUME=loadvolser
Note:

You will want to add these APF library definitions to a SYS1.PARMLIB(PROGxx) member so that these same authorizations are automatically activated during z/OS system initialization.

Parent topic: Quick Configuration


Define Mainframe Access to the Security Subsystem

Use RACF TSO commands to define the Mainframe Access started tasks (MFA, MFAAS and MFAS) and assign a userid and groupid to the tasks. The stcuserid should have appropriate access to the Mainframe Access data sets and should also have a basic OMVS RACF segment defined. At a minimum, the stcuserid OMVS segment must have a UID. The stcgroup must also have an OMVS segment with a GID. The following REDEFINE will provide the necessary definition for all of the started tasks (MFA, MFAAS and MFAS).

RDEFINE STARTED MFA*.* STDATA(USER(stcuserid) GROUP(stcgroup))
   OWNER(stcuserid)
SETROPTS RACLIST(STARTED) REFRESH

If you are using another security product such as CA-ACF2 or CA-Top Secret you will need to make similar updates to your security system definitions. MFA, MFAAS and MFAS will need a started task definition with an OMVS segment and they will need access to the SAF API for security subsystem calls. Please refer to your security product documentation.

Parent topic: Quick Configuration


Starting Mainframe Access

When you have completed all of the tasks described in the preceding sections you are ready to start Mainframe Access to perform some simple installation verification tests. Start Mainframe Access by issuing the following z/OS START command at a system console or using the TSO/ISPF SDSF command facility:

S MFA

Here is an example that shows the messages displayed during startup. The start command is issued for MFA, the name of the started task JCL sample that has been customized and copied into a system procedure library. The SERVERS sample also defines the Mainframe Access Data Connect server as an application server address space that should be started automatically by Mainframe Access during initialization. Mainframe Access issues an internal start command for MFAS, the name of the started task JCL sample for the Mainframe Access Data Connect server.

15:49:32.45 CSIRLW1  00000290  S MFA
15:49:32.47 STC05579 00000090  $HASP100 MFA ON STCINRDR
15:49:32.55 STC05579 00000290  IEF695I START MFA WITH JOBNAME MFA IS ASSIGNED TO USER RWITEK, GROUP DEVELOP
15:49:32.55 STC05579 00000090  $HASP373 MFA  STARTED
15:49:32.55 STC05579 00000090  IEF403I MFA - STARTED - TIME=15.49.32
15:49:32.85 STC05579 00000090  MFM0014I: Mainframe Access V4.00 (BASE) for YOUR_COMPANY_NAME
15:49:32.85 STC05579 00000090  MFM0066I: Address space type is CTLRGN
15:49:32.86 STC05579 00000090  MFM0057I: GTF user record id (eid) is 00E9
15:49:32.86 STC05579 00000090  MFM0012I: TCP port number is 1503
15:49:32.86 STC05579 00000090  MFM0013I: Admin port number is 1504
15:49:32.86 STC05579 00000090  MFM0047I: DSS maximum shared public files is 10
15:49:32.86 STC05579 00000090  MFM0055I: DSS scan interval is 30 minutes
15:49:32.86 STC05579 00000090  MFM0054I: SMF recording is off, record id is zero or invalid
15:49:32.87 STC05579 00000090  MFM0063I: MFA Direct is active
15:49:32.87 STC05579 00000090  MFM0064I: MFA Direct number of processing tasks is 5
15:49:33.16 STC05579 00000090  MFMDS052I CA/PanValet Ready
15:49:33.21 STC05579 00000090  MFMDS055I MCG/RPC feature inactive
15:49:33.22 STC05579 00000090  MFMDS001I DSS Server Ready
15:49:36.92 STC05579 00000090  MFM0001I: Mainframe Access V4.00 (BASE) is active
15:49:37.00 STC05580 00000090  $HASP100 MFAS ON STCINRDR
15:49:37.06 STC05580 00000090  $HASP373 MFAS  STARTED
15:49:37.06 STC05580 00000090  IEF403I MFAS - STARTED - TIME=15.49.37
15:49:37.23 STC05580 00000090  MFA302I.MFAS.MFDSTART / ATTACHING VTAM PROCESSOR
15:49:37.24 STC05580 00000090  MFA303I.MFAS.MFDSTART / MFA/DATACONNECT V4.00 BASE  COPYRIGHT (C)
                               1987-2007 MICRO FOCUS INTERNATIONAL LTD.
15:49:37.24 STC05580 00000090  MFA110I.MFAS.MFDFSQ00 / VTAM PROCESSOR ACTIVE USING VTAMAPPL MFA62ACB
Parent topic: Quick Configuration


Stopping Mainframe Access

Stop Mainframe Access by issuing the following z/OS STOP command at a system console or using the TSO/ISPF SDSF command facility:

P MFA

Here is an example that shows the messages displayed during shutdown. The stop command is issued only for Mainframe Access, the Mainframe Access server. Mainframe Access issues an internal stop command for MFAS, the application server address space for Mainframe Access Data Connect that was defined in the SERVERS member and started automatically by Mainframe Access. MFAS ends first and then Mainframe Access completes its shutdown processing.

16:44:18.52 CSIRLW1  00000290  P MFA
16:44:21.52 STC05579 00000290  P MFAS
16:44:21.53 STC05580 00000090  MFA112I.MFAS.MFAFSQ00 / VTAM PROCESSOR HAS TERMINATED
16:44:21.68 STC05580 00000090  MFA317I.MFAS.MFARSC00 / HAS BEEN TERMINATED
16:44:21.69 STC05579 00000090  MFMDS005I DSS Server shutdown
16:44:21.70 STC05580 00000090  IEF404I MFAS - ENDED - TIME=16.44.21
16:44:21.70 STC05580 00000090  $HASP395 MFAS  ENDED
16:44:32.77 STC05579 00000090  MFM0011I: Mainframe Access shutdown completed
16:44:32.82 STC05579 00000090  IEF404I MFA - ENDED - TIME=16.44.32
16:44:32.82 STC05579 00000090  $HASP395 MFA  ENDED
Parent topic: Quick Configuration


Advanced Configuration Activities

Mainframe Access is a general purpose server supporting a variety of Micro Focus client products. The Quick Configuration process that you have completed enables a large number of Mainframe Access server features that will satisfy most access requirements. This section describes the customizations (beyond the quick configuration) that are needed to enable various additional features of Mainframe Access server.

The following table summarizes the required updates on a per-feature basis. This will help you to select the correct configuration activities for a specific feature.

Feature | Customization
Audit Log | Refer to Allocating and Initializing an Audit Log Data Set to prepare the data set. Then see Editing Mainframe Access Parameters and update the audit log parameter to AUDIT LOG=YES.
Access List | Refer to Editing Access List Definitions for guidance in defining IP addresses and address ranges. Then see Editing Mainframe Access Parameters and update the access list check parameter to ACCESS LIST CHECK=YES.
CICS support | Using CICS support, clients can interact with z/OS CICS servers for file access, remote program execution, transaction execution, etc. Activate support for this feature by setting MCO FEATURE=YES and setting MCOLINK_MAXTASKS=2. The number of tasks supporting this feature can be increased in the future as your usage dictates. To complete the setup for this feature you will need to customize your client and the z/OS CICS server.
Remote IMS Option | Using the Remote IMS Option, clients can execute DL/I calls that are processed by a z/OS IMS server. Activate support for this feature by setting REMOTE IMS FEATURE=YES and setting IMSLINK_MAXTASKS=2. The number of tasks supporting this feature can be increased in the future as your usage dictates. To complete the setup for this feature you will need to customize your client and the z/OS IMS server. You must also install the Remote IMS server software in the target z/OS IMS server and enable APPC/MVS communications for that IMS server. All of the machine-readable installation materials for your Remote IMS Server can be found in the <hlq>.RIMS data set.
List DB2 | Mainframe Access' List DB2 feature dynamically identifies z/OS DB2 and IMS servers that are active on the z/OS system where Mainframe Access server is executing. This information can be helpful when defining these systems to Mainframe Access server and clients. Activate support for this feature by setting LIST DB2=YES .
Data Connect | Quick Configuration installs the Mainframe Access Data Connect server with SAF security checking active and without special customizations for PC to mainframe file name mapping. If you need to alter this basic setup see the appendix Data Connect .
Enterprise Server/Mainframe Subsystem Support | Enterprise Server/Mainframe Subsystem Support (ES/MSS) enables Mainframe Access server to accept CICS ISC requests initiated by z/OS CICS and route them to an ES/MSS server for execution. The combination of ES/MSS support and the CICS support creates a bi-directional ISC connection between ES/MSS and z/OS CICS. To complete the setup for this feature you need to customize your ES/MSS server(s) and the z/OS CICS server(s). See your Enterprise Server documentation and IBM z/OS CICS publications for help with these customizations.
ChangeMan interface | Mainframe Access' Source Connect feature works with ChangeMan to provide client access to ChangeMan-managed files. For more information see the section ChangeMan ZMF in the appendix External Library Management Systems .
Panvalet interface | Mainframe Access' Source Connect feature works with Panvalet to provide client access to Panvalet-managed files. For more information see the section Panvalet in the appendix External Library Management Systems .
Librarian interface | Mainframe Access' Source Connect feature works with Librarian to provide client access to Librarian-managed files. For more information see the section Librarian in the appendix External Library Management Systems .
Endevor interface | Mainframe Access' Source Connect feature works with Endevor to provide client access to Endevor-managed files. For more information see the section Endevor in the appendix External Library Management Systems .
Note:

As noted in the preceding customization summaries, you also need to prepare the external servers and clients that Mainframe Access works with.

  • Editing Mainframe Access Parameters
  • Editing Mainframe Access Server Definitions
  • Editing Access List Definitions
  • Allocating and Initializing an Audit Log Data Set
  • Adding Mainframe Access to TCP/IP's Autolog List
  • Setting Up a Mainframe Access GTF Procedure
Parent topic: Configuration
Related concepts
Quick Configuration
Prerequisites


Editing Mainframe Access Parameters

You edit the Mainframe Access parameter definitions located in member PARMS to customize them for your system. The sample parameter definitions are provided here as a convenient reference while you read. Lines that begin with an asterisk are treated as comments and are skipped in processing. All parameters must be contained on a single input statement and we recommend that you begin your parameter keywords in column 1. The first blank character following a parameter value indicates the end of the parameter keyword and value pair and any text following that blank is treated as a comment.

*--------------------------------------------------------------------*
*                                                                    *
* Micro Focus Mainframe Access - Initialization Parameters           *
*                                                                    *
* For minimum customization during installation you should review    *
* the following parameters and change them to suit your              *
* installation, if necessary.  These customizations will allow you   *
* to complete the installation and perform basic installation        *
* verification testing.  These minimum customizations are also       *
* sufficient to enable testing of MFA and SQL Option client          *
* functions.                                                         *
*                                                                    *
* TCP_PORT         port to be used by client applications            *

* NETWORK ID       see VTAM definitions in SYS1.VTAMLST(ACTSTRxx)    *
* LU62 APPLID      update if you changed sample MFAVTAM              *
* APPLID PASSWORD  update if you changed sample MFAVTAM              *
*                                                                    *
* Additional customization and/or setup work is required to enable   *
* the use of other product functions.  After installation            *
* verification testing, refer to the product documentation to        *
* continue with customization for these additional functions:        *
*                                                                    *
* CICS Option                                                        *
* IMS Option                                                         *
* MFA access list checking                                           *
* MFA audit logging                                                  *
* MFA support for external library managers                          *
* ES/MTO                                                             *
*                                                                    *
*                                                                    *
*                          Change Log                                *
*                                                                    *
*                                                                    *
* ChangeID  Description                                              *
* --------  -------------------------------------------------------- *
* 2.0       New parameter - MFA_JOBNAME_CHECK                        *
* 2.0       New parameter - MFA_GUI_IGNOREUSERCTO                    *
* 2.0       New parameter - MFA_GUI_BLANKPASSWORDS                   *
* SP2WS1HF6 New parameter - MFA_ACCEPT_EMPTY_FILES                   *
* SP2       New parameter - BIND_NETADDR=0.0.0.0                     *
* SP2       New parameter - MFA_MCG_DB2CONNECTION=RRSAF              *
* SP2       New parameter - CHANGEMAN_SSID=                          *
* SP2       New parameter - CHANGEMAN_ASGROUP=CGMQ                   *
* SP2       New parameter - CHANGEMAN_INTERFACE=SERXMLAC             *
* SP2       New parameter - CHANGEMAN_DSNQUALIFIER=                  *
* WS05HF1   New parameter - CHANGEMAN_COMMON_BUILD=NO                *
* WS05HF1   New parameter - CHANGEMAN_TEST_OPTION=NO                 *
* WS05HF1   New parameter - MFA_ENDEVOR_INTERFACE=YES                *
* WS05HF1   New parameter - MFA_PANVALET_INTERFACE=YES               *
* WS05HF1   New parameter - MFA_LIBRARIAN_INTERFACE=YES              *
* WS05HF1   New parameter - MFA_LIBRARIAN_DIR_INFO=LONG              *
* WS06      New parameter - ES/MTO OUTBOUND FEATURE=NO               *
* WS06      ChangeMan parameters moved to MFA services section       *
*--------------------------------------------------------------------*
*
*--------------------------------------------------------------------*
* General Parameters                                                 *
*--------------------------------------------------------------------*
*
SYSOUT=A                       --- Required if TRACE=SYSPRINT
ROUTE=(2,11)                   --- Console message route codes
ORGANIZATION=YOUR_COMPANY_NAME --- Company name (no embedded spaces)
ASTYPE=CTLRGN                  --- Parms for MFA control region
NETWORK ID=DDINET1             --- SNA network ID where MFA is running
LU62 APPLID=MFM62ACB           --- VTAM LU6.2 APPL
APPLID PASSWORD=MFM62PSW       --- VTAM LU6.2 APPL password
TRACE=SYSPRINT                 --- "SYSPRINT", "GTF" or "CONSOLE"
TRACING=NO                     --- Start tracing (YES/NO)
LIST PARMS=YES                 --- List parameters on sysout (YES/NO)
EID=00E9                       --- Required if TRACE=GTF
COMPRESSION=NO                 --- Compression for SQL Option traffic
ACCESS LIST CHECK=NO           --- Access List checking (YES/NO)
AUDIT LOG=NO                   --- Audit Logging (YES/NO)
TCP_PORT=2020                  --- TcpIp port for MFA, TELNET
BACKLOG=5                      --- TcpIp "listen" backlog
BUFFER SIZE=0                  --- TcpIp send/recv buffer size (0=MAX)
TIME OUT FOR CONNECTION=30     --- TcpIp idle timeout minutes (0=NONE)
TIME OUT FOR INITIAL RECV=10   --- Initial recv tot seconds (1<x<59)
MAX_PUBLIC_FILES=10            --- Dataset Services max shared files
DSS_SCAN_INTERVAL=30           --- Dataset Services scan interval
SMF_RECORDID=0                 --- SMF record ID
CGMQOTMA LOGDD=SYSOUT          --- CG production log DDname or "SYSOUT"
BIND_NETADDR=0.0.0.0           --- Hostname/IP address for listeners
*
*--------------------------------------------------------------------*
* Mainframe Access services parameters                               *
*--------------------------------------------------------------------*
*
MFA_ACCEPT_EMPTY_FILES         --- Download empty data sets (YES,NO)
MFA_ENDEVOR_INTERFACE=YES      --- Use Endevor   interface (YES,NO)
MFA_GUI_BLANKPASSWORD          --- Clear password field (YES,NO)
MFA_GUI_IGNOREUSERCTO          --- Disable inactivity timeout (YES,NO)
MFA_JOBNAME_CHECK              --- Batch job starts with submitter's ID (YES,NO)
MFA_PANVALET_INTERFACE=YES     --- Use Panvalet  interface (YES,NO)
MFA_LIBRARIAN_INTERFACE=YES    --- Use Librarian interface (YES,NO)
MFA_ENDEVOR_HISTORY=YES        --- Endevor MFALOGE history (YES,NO)
MFA_LIBRARIAN_HISTORY=YES      --- Librarian MFALOG history (YES,NO)
MFA_LIBRARIAN_UPD_MODULE=AFOLIBR - Librarian batch update module name
MFA_LIBRARIAN_DIR_INFO=LONG    --- Librarian dir list (SHORT or LONG)
MFA_PANVALET_HISTORY=YES       --- Panvalet MFALOG history (YES,NO)
MFA_PANVALET_UPD_MODULE=PAN#1  --- Panvalet batch update module name
MFA_SAF_HISTORY=YES            --- Data set access MFALOG history
MFA_SYSOUT_CLASS=A             --- MFALOG,MFALOGE,SNAPDUMP class
MFA_SYSOUT_DEST=LOCAL          --- MFALOG,MFALOGE,SNAPDUMP dest
MFA_MCG_DB2CONNECTION=RRSAF    --- MCG DB2 connection (CAF or RRSAF)
CHANGEMAN_SSID=                --- ChangeMan subsystem ID x ("SERx")
CHANGEMAN_ASGROUP=CGMQ         --- ChangeMan address space group name
CHANGEMAN_INTERFACE=SERXMLAC   --- ChangeMan XML batch client interface
CHANGEMAN_DSNQUALIFIER=        --- ChangeMan DSN qualifier
CHANGEMAN_COMMON_BUILD=NO      --- ChangeMan shared build opts (YES/NO)
CHANGEMAN_TEST_OPTION=NO       --- ChangeMan <TEST> option (YES/NO)
*
*--------------------------------------------------------------------*
* Services to be activated                                           *
*--------------------------------------------------------------------*
*
TCP LINK FEATURE=YES           --- SQL Option, Telnet client
MFADIRECT=YES                  --- Mainframe Access services
MFA FEATURE=YES                --- Mainframe Access Data Connect Server
PEM FEATURE=YES                --- Password Expiration Manager
MCO FEATURE=NO                 --- CICS Option
REMOTE IMS FEATURE=NO          --- IMS Option
LIST DB2=NO                    --- DB2 and IMS subsystem finder
ES/MTO OUTBOUND FEATURE=NO     --- ES/MTO Outbound support
ZSERVER FEATURE=YES            --- z/Server MFA service
*
*--------------------------------------------------------------------*
* Number of tasks to run for each service                            *
*--------------------------------------------------------------------*
*
TCPLINK_MAXTASKS=2             --- # of TCBS for TCP LINK feature
MFALINK_MAXTASKS=2             --- # of TCBS for MFA Server routing
MFADIRECT_MAXTASKS=5           --- # of TCBS for MFA processing
IMSLINK_MAXTASKS=0             --- # of TCBS for IMS Option
MCOLINK_MAXTASKS=0             --- # of TCBS for CICS Option
*
END
The order shown here is a logical one. However, you can enter the parameters in any order, as long as they are followed by the END marker. We strongly recommend that the SYSOUT and ROUTE parameters be specified at the beginning of the definitions to ensure that startup messages issued during the remainder of parameter processing reach the proper destinations. The following table lists and describes the parameters in alphabetical order.
Parameter | Description
ACCESS LIST CHECK | Indicates whether or not the access list feature is to be activated for clients. This enables you to restrict access to Mainframe Access according to the connecting client's IP address (see the section Editing Access List Definitions). Specify NO to accept all client connection requests, regardless of the client's IP address. Specify YES to permit client connections based on the PERMIT and REJECT rules for IP addresses defined in your access list.
APPLID PASSWORD | The ACF/VTAM ACB password to be used when Mainframe Access opens its VTAM ACB. Specify a password consisting of between one and eight characters. This value must match the password value specified by the PRTCT parameter in the Mainframe Access VTAM application program major node definition in VTAMLST.
ASTYPE Specifies the type of Mainframe Access server region. Valid values are CTLRGN, STANDARD and APPSERVER:
  • CTLRGN starts a full-function Mainframe Access server control region capable of managing dependent address spaces. This is the normal setting for your Mainframe Access server.
  • STANDARD (the default) starts Mainframe Access server without support for dependent address spaces. The standard server is full-function but it cannot automatically start and stop the Mainframe Access Data Connect server and Mainframe Access application servers.
  • APPSERVER starts a Mainframe Access server dependent region for transaction processing. This setting is used in the initialization parameters for application server regions that are started and controlled by a Mainframe Access server control region.
AUDIT LOG | Indicates whether or not the audit log is to be activated. Specify YES to activate or NO to deactivate. If audit logging is selected, be sure to complete the tasks described in the section Allocating and Initializing an Audit Log Data Set, above.
BACKLOG | The number of pending TCP/IP connection requests that the TCP/IP network software should hold while Mainframe Access is processing the current connection request. Connection processing is typically handled very quickly and a small backlog of between 5 and 10 should be adequate for most installations. If you have an unusually high number of concurrent connection requests, some end users might receive a connection reject message. Specify a positive integer value in the range 5 through 50.
BIND_NETADDR | Selects the network address(es) to which the Mainframe Access listening port (TCP_PORT) should be bound. Specify 0.0.0.0 (or omit this parameter) to bind the ports to all network addresses assigned to the host system. Specify a specific network address or a logical host name (64-character maximum) to restrict Mainframe Access to a single, specific host network address.
BUFFER SIZE | The maximum amount of data that Mainframe Access should send or receive through the TCP/IP network software in one send or receive operation. Specify 0 (zero) to allow Mainframe Access to use the optimum buffer size; this is recommended, as it will reduce the number of send or receive calls made to the TCP/IP network software. Specify an explicit value in the range 512 to 32767 only if you have diagnosed a problem with your TCP/IP network software that is associated with large message sizes.
CHANGEMAN_COMMON_BUILD | Specifies whether or not Mainframe Access accommodates group builds submitted under AppMaster Builder. Specify YES to enable group builds or NO to disable them. The default is NO. When enabled for group builds, MFA modifies the build options for each member of the AMB group to match the component name and type submitted, ensuring that each build request in the group is properly executed.
CHANGEMAN_DSNQUALIFIER Specifies a high-level qualifier for dynamically allocated data sets created by MFA Server to hold input files during the staging process. MFA Server creates these data sets dynamically as card-image sequential data sets that are deleted when the associated client request completes. The default qualifier is the login ID of the current user. You should set an alternate qualifier if your installation’s SERNET does not have RACF authority to read or write data into files stored in data sets named with the current user’s login ID as the high-level qualifier.

If an alternate qualifier is required, see your ChangeMan administrator or your security administrator for assistance in selecting a proper value.

If your ChangeMan functionality is restricted by security subsystem authorizations, you might need to specify your dataset high-level qualifier such that read access to the data sets is always permitted.

CHANGEMAN_INTERFACE Specifies the name of the ChangeMan ZMF module. During ChangeMan request processing, MFA Server loads and branch enters this module. Valid values are SERXMLBC and SERXMLAC. The default is SERXMLAC.

The preferred interface module is SERXMLAC, which is not documented by Serena; however, it provides better interface performance than SERXMLBC by using virtual storage instead of data sets for XML input and output exchange between MFA Server (the requester) and ChangeMan ZMF.

Serena documents only the SERXMLBC interface, which is the XML services batch client. SERXMLBC is intended for use in a batch job stream and requires XMLIN and XMLOUT DD statements to define its required data sets. The MFAAS JCL sample provides sample DD statements for XMLIN and XMLOUT; however, they are commented out. If you must use SERXMLBC, contact SupportLine for assistance with data set definitions.

This parameter is required in both the PARMS member and the PARMSAS member used by application server address spaces.

CHANGEMAN_SSID Initializes the Mainframe Access ChangeMan interface by providing the final character of the z/OS subsystem ID used to identify ChangeMan. Omit this parameter to bypass Mainframe Access initialization for the ChangeMan interface. Valid values are any single alphabetic or numeric character. The character specified is appended to the subsystem ID string "SER", completing the four-character ID. For example, if you specify CHANGEMAN_SSID=A, the z/OS subsystem ID becomes "SERA".

This parameter is required in both the PARMS member and the PARMSAS member used by application server address spaces.

Your ChangeMan administrator can help you to determine the correct subsystem ID to use.

CHANGEMAN_TEST_OPTION | Specify whether or not MFA uses the XML trace option. Specify YES to enable XML trace or NO to disable it. The default is NO. When enabled, SERNET logs information in XML format into the standard SERPRINT DD file. This file can be used to identify problems and to validate MFA services. Enabling XML trace is not recommended for production systems due to the large volume of log data generated.
COMPRESSION | Indicates whether or not Mainframe Access should apply data compression when communicating with SQL Option for DB2 clients. Specify YES to activate data compression or NO to deactivate it.
DSS_SCAN_INTERVAL | The time period in minutes between Data Set Services checks for abandoned buffers or open files. Due to unforeseen environmental errors, transactions may abnormally terminate while holding open files and other I/O resources. These scans locate idle resources and return them to an available status and ensure that no file is held idle for more than two consecutive scan intervals. Specify the number of minutes as an integer value between 30 and 90. The default is 30 minutes.
EID | The event ID of Mainframe Access GTF user trace records. The EID must be available for exclusive use by Mainframe Access and must match the USR=(eid) parameter specified to GTF when GTF is started (see the sample member GTFCNTL). This parameter is valid only when TRACE=GTF is specified. Specify a hexadecimal number of up to four bytes that GTF recognizes as a valid user trace record identifier.
ES/MTO OUTBOUND FEATURE Controls whether or not Mainframe Access accommodates ES/MSS. Specify YES to enable ES/MSS support or NO to disable it. The default is NO.

When disabled, MFA Server initialization ignores all ES/MSS server definitions contained in the SERVERS startup member.

When enabled, MFA Server processes ES/MSS server definitions at startup, initializing and allocating the VTAM ACBs defined for ES/MSS support. MFA Server also starts the required processes to manage ISC conversations initiated by the defined z/OS CICS systems to the defined ES/MSS servers.

IMSLINK_MAXTASKS | The number of z/OS subtasks (TCBs) to be started and dedicated to processing requests from IMS Option (Remote IMS) clients. Specify 0 (zero) or a positive integer value between 1 and 50.
LIST DB2 | Indicates whether or not the Mainframe Access LIST DB2 feature is to be activated. This obtains information about the DB2 and IMS subsystems. Specify YES to activate LIST DB2 or NO to deactivate it.
LIST PARMS | Controls the listing of Mainframe Access parameter definitions on the XDBOUT sysout data set. The parameter listing is helpful when you need to examine the active configuration settings. Specify YES to echo parameter definitions to the XDBOUT sysout data set or NO to inhibit the listing.
LU62 APPLID | The ACF/VTAM ACBNAME to be used by Mainframe Access. This ACBNAME must match the ACBNAME parameter of an active VTAM application major node (see the section Editing Mainframe Access Server Definitions ). Mainframe Access issues a VTAM OPEN request for this ACBNAME during startup and initialization fails if the OPEN is not successful. This ACBNAME (or the possibly different "network name" specified in the VTAM application major node definition) is the SNA LU name that identifies Mainframe Access to other applications in your SNA network. Specify the ACBNAME that has been defined and activated for Mainframe Access.
MAX_PUBLIC_FILES | The maximum number of shared public files that Mainframe Access Data Set Services should keep available. When the maximum is reached the next request for a new public file will be rejected, and you must close one of the item libraries to make space for the new one. Specify an integer value between 24 and 64. Defaults to 32.
MCOLINK_MAXTASKS | The number of z/OS subtasks (TCBs) to be started and dedicated to processing requests from CICS clients. Specify 0 (zero) or a positive integer value between 1 and 50.
MFA_ACCEPT_EMPTY_FILES | Indicates whether or not empty VSAM or VB data sets can be downloaded. Set to YES to allow empty files to be downloaded, or set to NO to restrict this. When the files are downloaded, they are converted to MF format using DFCONV. To enable this option, it must be placed in the member referenced by the DD name XDBIN, and the MFA client modules must be updated. The default value is YES.
MFADIRECT | Indicates whether or not Mainframe Access Source Connect and Drag & Drop services are to be activated. Specify YES to activate these services or NO to disable these services. The default value is YES (the recommended setting).
MFADIRECT_MAXTASKS | The number of z/OS subtasks (TCBs) to be started and dedicated to processing requests from Mainframe Access Drag & Drop and Source Connect clients, including Mainframe Access client functions and other development environment clients. Specify 0 (zero) or a positive integer value between 1 and 50. The default value is 5.
MFA_ENDEVOR_HISTORY | YES is the default. This will dynamically create a cumulative Endevor transaction history file (MFALOGE) to house the access history of all file access attempts using Endevor. The Endevor API interface produces this log for each access requested.
MFA_ENDEVOR_INTERFACE | YES is the default. Specify NO to prevent MFA Server from offering access to Endevor services.
MFA FEATURE | Indicates whether or not communication with the Mainframe Access Data Connect server is to be activated. Specify YES to activate the Mainframe Access Data Connect feature or NO to deactivate it.
MFA_GUI_BLANKPASSWORD | Set to YES to clear the password input field on the Drag and Drop user dialog.
MFA_GUI_IGNOREUSERCTO | Set to YES to disable the inactivity time-out on the Drag and Drop user dialog.
MFA_JOBNAME_CHECK | Set to YES to check that the batch job name starts with the submitter's userid.
MFA_LIBRARIAN_HISTORY | YES is the default. This will include a summary audit trail of all LIBRARIAN data accesses as part of the MFALOG output log.
MFA_LIBRARIAN_DIR_INFO | LONG is the default. This directs MFA Server to request complete member information from Librarian. The LONG specification significantly increases response time when accessing Librarian master files containing over 1,000 members. Specify SHORT to reduce the amount of member information requested from Librarian.
MFA_LIBRARIAN_INTERFACE | YES is the default. Specify NO to prevent MFA Server from offering access to Librarian services.
MFA_LIBRARIAN_UPD_MODULE | The name of the Librarian Batch update utility originally shipped as AFOLIBR by Computer Associates. If this module has not been renamed, then this parameter need not be specified.
MFALINK_MAXTASKS | The number of z/OS subtasks (TCBs) to be started and dedicated to processing requests from Mainframe Access Data Connect clients including Mainframe Access client functions originating in COBOL development environment clients. Specify 0 (zero) or a positive integer value between 1 and 50.
MFA_MCG_DB2CONNECTION | Controls which attachment facility is used by Mainframe Access Server for DB2 connections. Specify CAF (to use the DB2 call attach facility) or RRSAF (to use the DB2 Recoverable Resource Manager Services attachment facility). RRSAF is the default if this parameter is omitted.
MFA_PANVALET_HISTORY | YES is the default. This will include a summary audit trail of all user accesses to Panvalet as part of the MFALOG output log.
MFA_PANVALET_INTERFACE | YES is the default. Specify NO to prevent MFA Server from offering access to Panvalet services.
MFA_PANVALET_UPD_MODULE | The name of the Panvalet Batch update utility originally shipped as PAN#1 by Computer Associates. If this module has not been renamed, then this parameter need not be specified.
MFA_SAF_HISTORY | YES is the default. This will include a summary audit trail of all file access authorizations as part of the MFALOG output log.
MFA_SYSOUT_CLASS | Default value is A. This is used as the SYSOUT class for any held data produced by Mainframe Access. This includes MFALOG, MFALOGE, and SNAPDUMP message files.
MFA_SYSOUT_DEST | Default value is LOCAL. This is used as the SYSOUT destination for any held data produced by Mainframe Access. This includes MFALOG, MFALOGE, and SNAPDUMP message files.
NETWORK ID | The SSCP network ID used by ACF/VTAM on this z/OS system. This parameter must match the NETID parameter in the active ATCSTRxx VTAM start parameters member of VTAMLST. This Network ID value is used by Mainframe Access to build an LUWID (SNA Logical Unit of Work ID for LU6.2) when an LU6.2 conversation is allocated to the DB2 DDF. Specify the 1 to 8 character Network ID from ACF/VTAM's startup parameters.
ORGANIZATION | Your company name or other meaningful identifier up to 40 characters in length. Spaces are not permitted. Use underscores or other non-blank characters to separate words if necessary.
PEM FEATURE Indicates whether or not the Mainframe Access Password Expiration Manager (PEM) feature is to be activated.

PEM is used in some Micro Focus client products to allow users of the client software on PCs to change passwords for their z/OS user IDs without logging on directly to z/OS. This is especially useful when the security subsystem indicates that the current password is expired and must be replaced. Specify YES (this setting is recommended) to activate the PEM feature or NO to deactivate it.

REMOTE IMS FEATURE | Indicates whether or not communication with IMS subsystems used by the IMS Option (Remote IMS) is to be activated. Specify YES to activate the Remote IMS feature or NO to deactivate it.
ROUTE | The message route codes to be used by Mainframe Access when console messages are issued using the z/OS WTO (Write to Operator) and WTOR (Write to Operator with Reply) services. See your IBM system documentation for valid values.
SMF_RECORDID | The SMF user record ID that Mainframe Access should use when writing SMF (IBM's System Management Facility) records to the z/OS SMF data sets. If an SMF user record ID is specified, that ID value should be assigned to Mainframe Access exclusively. Specify a valid SMF user record ID number to activate the Mainframe Access SMF support. Specify 0 (zero), or omit the parameter altogether, to disable the writing of SMF records.
SYSOUT | The SYSOUT class for the XDBOUT data set if it is dynamically allocated. Mainframe Access operational messages and trace data (when TRACE=SYSPRINT is specified and tracing is active) are written to this data set. XDBOUT is dynamically allocated to this SYSOUT class if an XDBOUT DD statement is not present in the Mainframe Access JCL. Specify a SYSOUT class designator that is valid for your z/OS system.
TCP LINK FEATURE | Indicates whether or not the TCP/IP connection feature is to be activated. You must specify YES.
TCP_PORT | The port number to accept connections from Micro Focus clients.
TCPLINK_MAXTASKS | The number of z/OS subtasks (TCBs) to be started and dedicated to processing requests from SQL Option for DB2 clients. Specify a positive integer value between 1 and 50.
TIME OUT FOR CONNECTION | The number of minutes that a client connection can remain idle, after which the connection will be broken and Mainframe Access resources dedicated to the client will be released. Resources that are released when an idle client is disconnected include allocated storage, TCP/IP resources and connections to server subsystems such as DB2, IMS, CICS and Mainframe Access. Specify 0 (zero) to disable the client timeout feature and allow unlimited idle time, or a positive integer value.
TIME OUT FOR INITIAL RECV | The number of seconds that the listener process (Micro Focus client listener or Web Server listener) will wait to receive the initial client message after a socket connection has been accepted from a new client. If the time value expires before a complete initial message is received, the client is disconnected and the listening process prepares to accept another client connection request. The default value of 3 seconds is appropriate for all installations. This low value helps keep the listeners running smoothly, even during occasional network and/or client malfunctions. Specify a positive integer value between 1 and 59 (inclusive) to alter the time out value. This may be useful for diagnostic purposes.
TRACE The destination for trace data when tracing is activated.
  • Specify SYSPRINT to send print formatted trace output to the data set identified by the XDBOUT DD statement, normally a SYSOUT data set. We recommend this setting during initial product testing and when you are performing controlled problem determination.
  • Specify GTF to trace a very active Mainframe Access that is processing a high transaction volume. Trace data collected by GTF is written to external storage (tape or DASD) in a raw data format while tracing is active. You can use IBM's IPCS (Interactive Problem Control System) to format the data for analysis after tracing has been completed. Trace records are sent to the console if GTF is not available when TRACE=GTF is specified.
  • Specify CONSOLE to send trace output to the system log and console (not recommended because of the large volume of messages).
TRACING | Specifies whether or not detailed tracing of Mainframe Access Server program activity should be started during initialization processing. Normally tracing should be turned off during initialization and during normal product operation. Activity tracing writes detailed information to the XDBOUT sysout data set and this can slow down performance in a busy server. Tracing is normally controlled by the TRACE ON and TRACE OFF commands after initialization is complete. The TRACING parameter makes it possible to trace the initialization activity, before the server is ready to accept TRACE ON/OFF commands. Activity trace started by the TRACING parameter can be stopped later using the TRACE OFF command. Specify YES to activate tracing during initialization or specify NO to inhibit activity tracing until a TRACE ON command is issued.
ZSERVER FEATURE=YES | Indicates whether Mainframe Access Server should be paired with z/Server. Specify YES to activate the Mainframe Access server and z/Server service feature or NO to deactivate it.
Parent topic: Advanced Configuration Activities
Related information
Editing Access List Definitions
Allocating and Initializing an Audit Log Data Set
Editing Mainframe Access Server Definitions


Editing Mainframe Access Server Definitions

The SERVERS definitions describe both application servers and target servers. Target server definitions provide an ID label and the LU 6.2 parameters needed to contact the server using SNA LU 6.2 protocols. The ID label is used in some client configurations to select a specific target server.

Application servers define address spaces that can be started and controlled by Mainframe Access server. The definition provides a JCL procedure name that can be used to start the address space, a server program name, values that govern the number of address spaces that can be started, etc.

If you will be using CICS Option or IMS Option, you must edit the Mainframe Access sample target server definitions located in member SERVERS to customize them for your system. The application server and target server definitions for the Mainframe Access Data Connect server will need to be edited only if you have changed the JCL procedure name or the VTAM APPL ACBNAME, or if the default logmode name cannot be used. All parameters for one target server should be grouped together following the <…ID…> assignment that starts the definition. The <END> statement is used to end each target server definition. All parameters for one application server should be grouped together following the <ASGROUP…> assignment that starts the definition. The <END> statement is used to end each application server definition.

The sample definitions for target servers that you will not be using can be left as they are and they will not affect the operation of Mainframe Access with target servers that you have customized. For example, if you are not using CICS Option you can leave the sample CICS target server definitions unchanged in the SERVERS member; or you can change each line of the unused definitions to a comment by inserting an asterisk in column 1; or you can delete them altogether.

The sample server definitions are provided here as a convenient reference while you read. Lines that begin with an asterisk are treated as comments and are skipped in processing.

*--------------------------------------------------------------------*
*                                                                    *
* Micro Focus Mainframe Access - Server Definitions                  *
*                                                                    *
* For minimum customization during installation you should review    *
* the following parameters and change them to suit your              *
* installation, if necessary.  These customizations will allow you   *
* to complete the installation and perform basic installation        *
* verification testing.  These minimum customizations are also       *
* sufficient to enable testing of MFA and SQL Option client      *
* functions.                                                         *
*                                                                    *
* ASPROC=MFAS      update if you changed the name of the MFAS sample *
*                  JCL procedure for the MFA Data Connect server     *
*                                                                    *
* ASPROC=MFAAS     update if you changed the name of the MFAAS       *
*                  sample JCL procedure for the Application Servers. *
*                                                                    *
* LUNAME=MFA62ACB  update if you changed sample MFAVTAM.             *
*                  This name must match the name in the MFAVTAM      *
*                  definition and the startup parameter value on     *
*                  the MFAS PROC statement.                          *
*                                                                    *
* Additional customization and/or setup work is required to enable   *
* the use of other product functions.  After installation            *
* verification testing, refer to the product documentation to        *
* continue with customization for these additional functions:        *
*                                                                    *
* CICS Option                                                    *
* IMS Option                                                     *
* ES/MTO                                                             *
*                                                                    *
*                          Change Log                                *
*                                                                    *
*                                                                    *
* ChangeID  Description                                              *
* --------  -------------------------------------------------------- *
* WS06      New server definition - Two ES/MTO server samples added  *
*--------------------------------------------------------------------*
*
*--------------------------------------------------------------------*
* Application Server address space definitions                       *
*--------------------------------------------------------------------*
*
* Mainframe Access Server (Data Connect) address space
*
<ASGROUP=MFAS>
ASPROC=MFAS
ASJOB=*
ASSERVER=MFARSC00
ASMINIMUM=1
ASMAXIMUM=1
ASGROUPID=0
<END>
*
* Mainframe Access Application Server(s) for Endevor
*
<ASGROUP=ENDV>
ASPROC=MFAAS
ASJOB=MFAE
ASSERVER=DACALL
ASMINIMUM=0
ASMAXIMUM=2
ASGROUPID=0
<END>
*
* Mainframe Access Application Server(s) for CG processing
*
<ASGROUP=CGMQ>
ASPROC=MFAAS
ASJOB=MFAC
ASSERVER=DACALL
ASMINIMUM=0
ASMAXIMUM=2
ASGROUPID=0
<END>
*
*--------------------------------------------------------------------
* MFA Data Connect server - only one DEFAULT server is supported
*--------------------------------------------------------------------
*
<MFAID=DEFAULT>
LUNAME=MFA62ACB
TPNAME=FILESHR2
MODENAME=#INTER
SYNCLEVEL=1
SECURITY=NONE
<END>
*
*--------------------------------------------------------------------
* Sample IMS servers - multiple servers may be defined
*--------------------------------------------------------------------
*
<IMSID=IMSA>
LUNAME=IMSSYSA
TPNAME=MFDBTP6
MODENAME=IBMRDB
SYNCLEVEL=0
SECURITY=NONE
<END>
*
<IMSID=DEFAULT>
LUNAME=IMSTEST
TPNAME=MFDBTP6
MODENAME=IBMRDB
SYNCLEVEL=0
SECURITY=NONE
<END>
*
*--------------------------------------------------------------------
* Sample CICS servers - multiple servers may be defined
*--------------------------------------------------------------------
*
<MCOID=CICA>
LUNAME=CICSSYSA
TPNAME=*
MODENAME=#INTER
SYNCLEVEL=0
SECURITY=NONE
<END>
*
<MCOID=DEFAULT>
LUNAME=CICSTEST
TPNAME=*
MODENAME=#INTER
SYNCLEVEL=0
SECURITY=NONE
<END>
*
*--------------------------------------------------------------------
* Sample ES/MTO servers - multiple servers may be defined
*--------------------------------------------------------------------
*
<ES/MTOID=MTO1>
ACBNAME=MFAMTO1
IPADDRESS=YOUR.MTO.HOSTNAME
PORT=2200
SESSIONS=4
SOCKETS=1
<END>
*
<ES/MTOID=MTO2>
ACBNAME=MFAMTO2
IPADDRESS=101.102.103.104
PORT=3300
SESSIONS=4
SOCKETS=1
<END>
*
*--------------------------------------------------------------------
* Sample CG MQ OTMA queue defintions - multiple queues may be defined
*--------------------------------------------------------------------
*
<CGMQOTMA=MYQ1>
QMANAGER=QMG1
QUEUE=MESSAGE.QUEUE.NUMBER1
ASGROUP=CGMQ
WAIT=4
<END>
*
<CGMQOTMA=MYQ2>
QMANAGER=QMG2
QUEUE=MESSAGE.QUEUE.NUMBER2
ASGROUP=CGMQ
WAIT=4
<END>
*
*--------------------------------------------------------------------
* Sample MFA and z/Server - For one MFA and z/Server instance with a
* STC scheduler and a CEA scheduler.
*--------------------------------------------------------------------
*
<ZSID=ZSRVDEF>
ZSJOB=TAURISPF
ZSIPADDRESS=127.0.0.1
ZSPORT=1200
ZSCEAPORT=1250
ZSDEFAULT=Y
<END>
*
  • Application Server Parameters for the Mainframe Access Data Connect Server
  • Target Server Parameters for ES/MSS
  • Target Server Parameters for the Mainframe Access Data Connect Server
  • Target Server Parameters for IMS Option (Remote IMS)
  • Target Server Parameters for CICS
  • Target Server Parameters for z/Server
  • Application Server Parameters for ChangeMan Processing
  • Application Server Parameters for Mainframe Access Endevor Support
Parent topic: Advanced Configuration Activities


Application Server Parameters for the Mainframe Access Data Connect Server

Parameter | Description
<ASGROUP=MFAS> | Signals the beginning of a Mainframe Access Data Connect application server definition. The group name must be MFAS for the Data Connect server. Specify MFAS.
ASPROC | The name of the started task JCL procedure that can be used to start the Data Connect server. This procedure must be stored in a procedure library that is available to z/OS START command processing. The Mainframe Access Data Connect server JCL is distributed as member MFAS but this name may be changed to suit your installation. Specify a JCL procedure name of up to eight characters.
ASJOB | The jobname prefix to be used for address spaces that are started for this group. For multiple-instance address spaces this is a prefix of 1 to 4 characters and Mainframe Access server will pad this prefix to a full 8-character jobname by appending a 4 to 7 digit sequence number. For example, ASJOB=ABC will result in jobnames ABC00001, ABC00002, etc. If you specify an asterisk (*) for this parameter the JCL procedure name is used for the jobname. This is appropriate for single-instance application server address spaces. The Mainframe Access Data Connect server is single-instance (only one will be started) and the JCL procedure name is appropriate for the jobname, also. Specify *.
ASSERVER | Specifies the name of the processing module for requests sent to this application server. Specify MFARSC00.
ASMINIMUM | Specifies the minimum number of address spaces that Mainframe Access server will start for a multiple-instance group during initialization. Mainframe Access Data Connect server is a single-instance server. Specify 1.
ASMAXIMUM | Specifies the maximum number of address spaces that Mainframe Access server will start for a multiple-instance group. Additional address spaces beyond the minimum will be started in response to transaction load, up to the maximum allowed by this specification. Mainframe Access Data Connect server is a single-instance server. Specify 1.
ASGROUPID | Specifies a numeric ID that can be used in client requests to identify this application server group. Data Connect clients do not use the ASGROUPID feature. Specify 0.
<END> | Signals the end of this application server definition.
Parent topic: Editing Mainframe Access Server Definitions


Target Server Parameters for ES/MSS

These statements define an ES/MSS server and provide MFA Server with the information needed to establish a TCP/IP socket connection to the ES/MSS server. This definition also creates a VTAM ACB that represents the ES/MSS server to the z/OS CICS system(s).

Parameter | Description
<ES/MTOID=xxxx> | Signals the beginning of an ES/MSS target server definition and assigns an ID to this server definition. The MTOID can be one to four characters in length and must match the SYSID of the ES/MSS server being defined. The initial connection messages exchanged by MFA Server and ES/MSS use this MTOID.
ACBNAME | The name of the VTAM ACB associated with this ES/MSS server. MFA Server OPENs and initializes this ACBNAME during startup. The z/OS CICS system(s) must be configured to communicate with this ES/MSS server through this VTAM ACB name using CICS CONNECTION and SESSIONS definition statements.
IPADDRESS | The internet host name or IP address of the ES/MSS server. Specify either the host name that resolves to the correct IP address or the actual IP address in standard dotted-decimal format. The combination of IPADDRESS and PORT from this definition provides MFA Server with the information it needs to originate a socket connection to ES/MSS and to verify the authenticity of a socket connection request from ES/MSS.
PORT | The port number where ES/MSS is listening for ISC connections.
SESSIONS | Specifies the number of concurrent conversations MFA Server can initiate to the ES/MSS server over a single socket connection. If ES/MSS has a different definition for the number of concurrent sessions, the session count is negotiated to a common value at the time a socket connection is established. Specify a value that supports the required number of concurrently active conversations for your application.
SOCKETS | Specifies the maximum number of concurrent socket connections between MFA Server and the ES/MSS server. ES/MSS support is currently limited to a single socket connection between MFA Server and an ES/MSS server; therefore, specify a value of 1.
<END> | Signals the end of this target server definition.
Parent topic: Editing Mainframe Access Server Definitions


Target Server Parameters for the Mainframe Access Data Connect Server

Parameter | Description
<MFAID=DEFAULT> | Signals the beginning of a Mainframe Access Data Connect target server definition. Data Connect client requests do not specify a target server ID and Mainframe Access always looks for the DEFAULT Mainframe Access Data Connect target server definition. Specify DEFAULT.
NETID | The network ID of your SNA network. Specify a network ID of up to eight characters.
LUNAME | The LU name of the Mainframe Access Data Connect server (also known as the ACBNAME or VTAM APPLID). Specify an LU name of up to eight characters.
TPNAME | The transaction program name for Mainframe Access Data Connect server requests. Specify FILESHR2.
MODENAME | The SNA log mode name that will be used by Mainframe Access to indirectly specify SNA session parameters when Mainframe Access initiates sessions with the Mainframe Access Data Connect server. Specify a log mode name for LU6.2 sessions of up to eight characters. This log mode name must be present in the VTAM log mode table available to Mainframe Access. IBM's default log mode table, ISTINCLM, typically provides several standard log modes that can be used by Mainframe Access, including both IBMRDB and #INTER LU6.2 log modes.
SYNCLEVEL | The SNA LU6.2 sync level option to be used on conversations with the Mainframe Access Data Connect server. Specify 1. Conversations use LU6.2 CONFIRM protocols.
SECURITY | The security level to be indicated in SNA LU6.2 Attach FMH-5 requests sent to the Mainframe Access Data Connect server. Mainframe Access forwards security subfield information as provided by the Data Connect client and sets the FMH-5 fields accordingly. Specify NONE.
<END> | Signals the end of this target server definition.
Parent topic: Editing Mainframe Access Server Definitions


Target Server Parameters for IMS Option (Remote IMS)

Parameter | Description
<IMSID=xxxx> | Signals the beginning of an IMS target server definition and assigns an ID to this server definition. If an IMS Option client request does not specify a target server ID or the specified target server ID does not exist, Mainframe Access selects the DEFAULT IMS target server, if one has been defined. This IMS target server ID name is used in the configuration of the client. When a Remote IMS request is sent this name is sent in the request data and is used to locate the target server definition for the IMS system that will receive the request. Specify DEFAULT or an ID of up to four alphanumeric characters.
LUNAME | The LU name of the IMS server (also known as the ACBNAME or VTAM APPLID). Specify an LU name of up to eight characters. This name must match the ACBNAME defined in an APPC/MVS LU definition for the target IMS system.
TPNAME | The IMS server transaction program name for IMS Option transactions. This is the LU6.2 transaction program name that will be sent to the IMS server in SNA Attach FMH-5 requests to begin an IMS Option transaction. Specify the APPC/MVS transaction program name that was specified in the APPC/MVS definitions during installation of Remote IMS.
MODENAME | The SNA log mode name that will be used by Mainframe Access to indirectly specify SNA session parameters when Mainframe Access initiates sessions with the IMS server. Specify a log mode name for LU6.2 sessions of up to eight characters. This log mode name must be present in the VTAM log mode table available to Mainframe Access. IBM's default log mode table, ISTINCLM, typically provides several standard log modes that can be used by Mainframe Access, including both IBMRDB and #INTER LU6.2 log modes.
SYNCLEVEL | The SNA LU6.2 sync level option to be used on conversations with the IMS server. Specify 0.
SECURITY | The security level to be indicated in SNA LU6.2 Attach FMH-5 requests sent to the IMS server. Mainframe Access forwards security subfield information as provided by the IMS Option client and sets the FMH-5 fields accordingly. Specify NONE.
<END> | Signals the end of this target server definition.
Parent topic: Editing Mainframe Access Server Definitions


Target Server Parameters for CICS

Parameter | Description
<MCOID=xxxx> | Signals the beginning of a CICS target server definition and assigns an ID to this server definition. If a CICS client request does not specify a target server ID or the specified target server ID does not exist, Mainframe Access selects the DEFAULT CICS target server, if one has been defined. This CICS target server ID name is used in the configuration of the client. When a CICS request is sent to Mainframe Access this name is sent in the request data and is used to locate the target server definition for the CICS system that will receive the request. Specify DEFAULT or an ID of up to four alphanumeric characters.
LUNAME | The LU name of the CICS server (also known as the ACBNAME or VTAM APPLID). Specify an LU name of up to eight characters.
TPNAME | The server transaction program name for CICS requests. This is the LU6.2 transaction program name that will be sent to CICS in SNA Attach FMH-5 requests to begin a CICS transaction. Specify a transaction program name of up to eight characters or specify * to cause Mainframe Access to use the transaction program name provided by the CICS client. The CICS client prepares a partial FMH-5 request that specifies the standard CICS transaction program names for function shipping, distributed program linking and so on.
MODENAME | The SNA log mode name that will be used by Mainframe Access to indirectly specify SNA session parameters when Mainframe Access initiates sessions with mainframe CICS. Specify a log mode name for LU6.2 sessions of up to eight characters. This log mode name must be present in the VTAM log mode table available to Mainframe Access. IBM's default log mode table, ISTINCLM, typically provides several standard log modes that can be used by Mainframe Access, including both IBMRDB and #INTER LU6.2 log modes.
SYNCLEVEL | The SNA LU6.2 sync level option to be used on conversations with CICS. Specify 0.
SECURITY | The security level to be indicated in SNA LU6.2 Attach FMH-5 requests sent to the CICS server. Mainframe Access forwards security subfield information as provided by the CICS client and sets the FMH-5 fields accordingly. Specify NONE.
<END> | Signals the end of this target server definition.
Parent topic: Editing Mainframe Access Server Definitions


Target Server Parameters for z/Server

Parameter | Description
<ZSID> | Signals the beginning of a z/Server definition and assigns an ID to this server definition.
ZSJOB | The STC ID specifies the target z/Server scheduler being redirected to. For a default installation this is TAURISPF. This is the value typed in the Scheduler Name field in the New Connection dialog box when adding a new Micro Focus z/Server connection in the Remote Systems view. This is ignored if DEFAULT is used as the Scheduler Name.
ZSIPADDRESS | The internet host name or IP address where the z/Server scheduler is running. Typically this is the same IP address of the machine that is hosting both MFA and z/Server.
ZSPORT | The STC scheduler port of the target STC scheduler being redirected to. A default installation has the value 1200.
ZSCEAPORT | The target CEA scheduler port being redirected to. A default installation has the value 1250.
ZSDEFAULT | The default configuration. If you type DEFAULT in the Scheduler Name field of the New Connection dialog box then these are the details that are returned.
<END> | Signals the end of this target server definition.

Example of multiple z/Server schedulers

You can have multiple configuration blocks defining multiple z/Server schedulers:

<ZSID=ZSRVDEF>
ZSJOB=TAURHLD
ZSIPADDRESS=127.0.0.1
ZSPORT=1200
ZSCEAPORT=1250
ZSDEFAULT=Y
<END>

<ZSID=ZSN>
ZSJOB=TAURHLF
ZSIPADDRESS=127.0.0.1
ZSPORT=2200
ZSCEAPORT=2250
<END>
In this example, if you type DEFAULT in the Scheduler Name field of the New Connection dialog box, then you get the information in the ZSID=ZSRVDEF block. If there are multiple ZSDEFAULT blocks, then the first block is always returned to you.
Note: Micro Focus recommends that you only specify ZSDEFAULT=Y in one block.

If you type TAURHLF in the Scheduler Name field of the New Connection dialog box, then you get the information from the ZSJOB=TAURHLF block.

If you type DEFAULT in the Scheduler Name field of the New Connection dialog box, then you get an error message that the default configuration could not be found:
No default z/Server Scheduler configured.
If you specify a Scheduler Name that does not exist you get an error message saying that a matching scheduler could not be found:
Unable to find matching server details for z/Server Scheduler named Scheduler Name.

If you omit the ZSCEAPORT from a block, then the default value of 1250 is used as the target CEA scheduler port.

You can only have one ZSPORT per block. If you have multiple z/Server schedulers on different ports then you need to have separate configuration blocks for each scheduler.

Parent topic: Editing Mainframe Access Server Definitions


Application Server Parameters for ChangeMan Processing

ChangeMan requests are processed in application server address spaces. A single group of application server address spaces can be defined for ChangeMan processing. The parameters in the group definition provide information that Mainframe Access Server needs in order to start and manage the associated address spaces.

ChangeMan processing is associated with a specific address space group by the Mainframe Access Server startup parameter CHANGEMAN_ASGROUP in the PARMS member. You may want to create a distinct ASGROUP definition for ChangeMan processing. This might be done to separate the workload for usage reporting, workload management, etc.

The MFAAS JCL sample referenced in the address space group definition contains comments that describe how to customize this JCL for ChangeMan processing.

Parent topic: Editing Mainframe Access Server Definitions


Application Server Parameters for Mainframe Access Endevor Support

Parameter | Description
<ASGROUP=ENDV> | Signals the beginning of the application server definition for Mainframe Access Endevor support. The group name must be ENDV. Specify ENDV.
ASPROC | The name of the started task JCL procedure that can be used to start address spaces for this group. Sample JCL procedure MFAAS provides the basic JCL for an application server address space. Refer to the section Endevor in the appendix External Library Management Systems to learn how to customize this JCL for Endevor support. Specify a JCL procedure name of up to eight characters.
ASJOB | The jobname prefix to be used for address spaces that are started for this group. For multiple-instance address spaces this is a prefix of 1 to 4 characters and Mainframe Access Server will pad this prefix to a full 8-character jobname by appending a 4 to 7 digit sequence number. For example, ASJOB=MFAE will result in jobnames MFAE0001, MFAE0002, etc. Endevor support multiple-instance address spaces to allow concurrent execution of client requests. The sample prefix MFAE can be changed to meet the needs of your installation. If you do change the suggested prefix you will need to review the security subsystem definition for the Mainframe Access started tasks. The configuration process uses a generic STARTED task definition (the generic name specified during Quick Configuration is MFA*.*) that covers generated jobnames such as MFAExxxx, in addition to the MFA (the MFA Server control region) and MFAS (the MFA Server for Data Connect) started task names. Specify a jobname prefix of up to four characters.
ASSERVER | Specifies the name of the processing module for requests sent to the application server. Specify DACALL.
ASMINIMUM | Specifies the minimum number of address spaces that Mainframe Access server will start for a multiple-instance group during initialization. Specifying zero delays address space activation until the first client request is received. Specify a minimum value from zero up to the ASMAXIMUM value.
ASMAXIMUM | Specifies the maximum number of address spaces that Mainframe Access server will start for a multiple-instance group. Additional address spaces beyond the minimum will be started in response to transaction load, up to the maximum allowed by this specification. Endevor support can effectively utilize multiple address spaces to meet the concurrency requirement demanded by your transaction arrival rate. The sample suggests an initial value of 2 and this can be increased as your transaction load increases. Mainframe Access server issues messages (to the XDBOUT data set) when a client request must be queued to wait for an available processing address space. Increase the ASMAXIMUM value (by 1) when you observe frequent queueing of client requests. Specify a value from 1 to 10.
ASGROUP | Specifies a numeric ID that can be used in client requests to identify this application server group. The Mainframe Access Endevor clients do not use the ASGROUP ID feature. Specify 0.
<END> | Signals the end of this application server definition.
Parent topic: Editing Mainframe Access Server Definitions
Related information
Endevor


Editing Access List Definitions

You must edit the access list definitions located in member ACCESS to customize them for your installation. The definitions in this list are:

  • PERMIT and REJECT lines - these specify the IP addresses from which client connections will be allowed or rejected. Client connection requests are checked only if the Mainframe Access parameter ACCESS LIST CHECK is set to YES. You must customize the PERMIT and REJECT lines with appropriate values for your implementation

The sample access list definitions are provided here as a convenient reference while you read. Lines that begin with an asterisk are treated as comments and are skipped in processing.

*--------------------------------------------------------------------*
*                                                                    *
* Micro Focus Mainframe Access - Access List                         *
*                                                                    *
*--------------------------------------------------------------------*
*
*--------------------------------------------------------------------*
* Permission list                                                    *
*--------------------------------------------------------------------*
*
PERMIT=111.111.111
*
*--------------------------------------------------------------------*
* Rejection list                                                     *
*--------------------------------------------------------------------*
*
REJECT=222.222.222
*
END
  • Permission and Rejection Lists
Parent topic: Advanced Configuration Activities


Permission and Rejection Lists

If you specify ACCESS LIST CHECK=YES in the Mainframe Access parameter file and specify the access list filename in an //XDBACC DD statement in the Mainframe Access startup JCL, client connection requests are accepted or rejected according to the values you specify for the PERMIT and REJECT parameters:

PERMIT=ipaddress
REJECT=ipaddress

The format of the IP address is the familiar dotted decimal notation. A complete Internet address consists of four decimal numbers or address groups, each in the range 0 through 255, with the groups being separated by decimal points.

You can specify complete Internet addresses to permit or reject individual clients.

You can also specify a range of consecutive Internet addresses in a single statement, by omitting one or more trailing address groups. This is known as a masked address specification. To decide whether or not a particular request is to be allowed, Mainframe Access first shortens the client address by removing trailing address groups that correspond to address groups omitted in the specification, then compares the shortened address with the masked address.

If you are using the access list mechanism, client connection requests from all addresses not specified in PERMIT or REJECT parameters are rejected.

Here are two example sets of access list parameters

  • Example 1
  • Example 2
Parent topic: Editing Access List Definitions


Example 1

PERMIT = 111.111.148
REJECT = 111.111.148.244

The effect of these parameter values is that all client connection requests from IP addresses in the range 111.111.148.0 to 111.111.148.255 are accepted with the exception of client address 111.111.148.244. Client connections from all other IP addresses are rejected.

Parent topic: Permission and Rejection Lists


Example 2

PERMIT = 11.1.82
REJECT = 11.1.82.4
PERMIT = 111.202.111.18

The effect of these parameter values is that all client connection requests from IP addresses in the range 11.1.82.0 through 11.1.82.255 are accepted with the exception of client address 11.1.82.4. Client connections requests from the address 11.202.111.18 are also accepted. Connection requests from all other IP addresses are rejected

Parent topic: Permission and Rejection Lists


Allocating and Initializing an Audit Log Data Set

The Mainframe Access audit log feature uses a VSAM data set to record client login and logout information. The information that is logged includes the user ID, client IP address, login and logout times, target server name and encryption usage. If you want to use the audit log feature you need to prepare the audit log data set and update the Mainframe Access JCL procedure.

Sample member AUDIT contains the JCL to allocate and initialize a Mainframe Access audit log VSAM data set. Edit the JOB card, data set names and volume serial number information, then submit the job and verify that the condition code for the INITLOG step is 0 (zero). Note that a condition code of 8 for the ALLOCLOG step is normal the first time that you run this job.

When editing the data set names you may use a global change command to change all instances of HLQ to the high level qualifier that you selected for Mainframe Access data sets during the installation procedure.

Edit the Mainframe Access startup JCL to make the audit log data set available. Do this by removing the keyword DUMMY and the trailing comma (DUMMY,) from the XDBAUDIT DD statement:

    //*
    //*-----------------------------
    //* Optional audit log data set
    //*-----------------------------
    //*
    //XDBAUDIT DD  DUMMY,DISP=SHR,DSN=&DSNQUAL..AUDIT
Parent topic: Advanced Configuration Activities


Adding Mainframe Access to TCP/IP's Autolog List

If you are using IBM's TCP/IP, you can add the Mainframe Access started task name (the name of the Mainframe Access JCL procedure in the system procedure library) to the TCP/IP autolog list. TCP/IP will then automatically start Mainframe Access when it starts and stop Mainframe Access when it stops. Do not perform this update until you have finished configuring Mainframe Access and are satisfied with the way Mainframe Access is running.

Parent topic: Advanced Configuration Activities


Setting Up a Mainframe Access GTF Procedure

Mainframe Access provides sample members MFAGTF and GTFCNTL to assist you when you need to use IBM's Generalized Trace Facility (GTF) to obtain trace data for problem determination. In some problem situations our Product Support will request a VTAM trace of an application LU, usually the Mainframe Access server LU.

  • Adding the GTF Procedure to a System Procedure Library
  • Testing the Mainframe Access GTF Procedure
Parent topic: Advanced Configuration Activities


Adding the GTF Procedure to a System Procedure Library

Sample JCL to run GTF as a started task is provided in member MFAGTF. Edit this JCL to customize the data set names for your installation and then copy the JCL into a system procedure library that is available when z/OS START commands are processed. Member GTFCNTL contains GTF control statements that are referenced by the sample GTF JCL procedure. The USR=(FF1,FEF,0E9) statement in this member specifies the recording of VTAM buffer trace records (FF1 and FEF) and Mainframe Access server trace records (0E9).

Note:

If you change the Mainframe Access EID=00E9 parameter setting (Editing Mainframe Access Parameters), you should update member GTFCNTL with the new value.

Parent topic: Setting Up a Mainframe Access GTF Procedure
Related information
Editing Mainframe Access Parameters


Testing the Mainframe Access GTF Procedure

After you customize and install procedure MFAGTF you can test out the procedure by issuing the following z/OS START command at a system console or using the TSO/ISPF SDSF command facility:

S MFAGTF.MYGTF

GTF will start and read the GTFCNTL parameter file. When the initialization complete message is issued GTF is ready to record trace data.

S MFAGTF.MYGTF
$HASP100 MFAGTF   ON STCINRDR
IEF695I START MFAGTF WITH JOBNAME MFAGTF IS ASSIGNED TO USER RWITEK, GROUP CSIDVLP
$HASP373 MFAGTF   STARTED
IEF403I MFAGTF - STARTED - TIME=19.08.44
AHL121I  TRACE OPTION INPUT INDICATED FROM MEMBER GTFCNTL OF PDS
<hlq>.CNTL
TRACE=USRP
USR=(FF1,FEF,0E9)
END
AHL103I  TRACE OPTIONS SELECTED --USR=(FEF,FF1,0E9)
AHL906I THE OUTPUT BLOCK SIZE OF    27998 WILL BE USED FOR OUTPUT 228
        DATA SETS:
          <hlq>.TRACE
AHL080I GTF STORAGE USED FOR GTF DATA: 229
        GTFBLOCK STORAGE       82K BYTES (BLOK=        40K)
        PRIVATE STORAGE      1038K BYTES
        SADMP HISTORY          54K BYTES (SADMP=       40K)
        SDUMP HISTORY          54K BYTES (SDUMP=       40K)
        ABEND DUMP DATA         0K BYTES (ABDUMP=       0K)
AHL031I GTF INITIALIZATION COMPLETE

You stop GTF by issuing the following z/OS STOP command at a system console or using the TSO/ISPF SDSF command facility:

P MYGTF

GTF acknowledges the stop command and closes down, as shown in the following example:

P MYGTF
AHL006I GTF ACKNOWLEDGES STOP COMMAND
IEF404I MFAGTF - ENDED - TIME=19.10.31
$HASP395 MFAGTF   ENDED
$HASP250 MFAGTF PURGED -- (JOB KEY WAS B9C101AA)
Parent topic: Setting Up a Mainframe Access GTF Procedure


Running Multiple Instances of Mainframe Access Server

Mainframe Access server is a robust server that is designed to efficiently handle all of the different client access requirements in high-volume usage. A single instance of Mainframe Access server will most likely meet the needs of your installation. It is, however, possible to run multiple instances of Mainframe Access server on your z/OS system. This might be desirable for establishing test and production servers, isolating specific user groups in their own server, isolating specific feature activations, etc.

Once you have a successful Mainframe Access server installation you can easily create additional instances as follows:

  • Create and activate VTAMLST APPL definitions for a new Mainframe Access server and a new Mainframe Access Data Connect server.
  • Reserve a unique TCP/IP port for the new Mainframe Access server (a TCP_PORT).
  • Create unique PARMS, SERVERS and ACCESS members for the new instance and customize them appropriately. You will definitely need to create a unique PARMS member and assign unique values to the LU62 APPLID= and TCP_PORT= parameters. It is possible to share ACCESS definitions, if that will meet the needs of your configuration. An alternative method would be to create a copy of the CNTL data set and retain the original member names.
  • Allocate a unique audit log data set for the new instance if you are using this feature.
  • Create a copy of the MFA proc in the proclib data set and update the JCL to reference the new PARMS, SERVERS and ACCESS members for this instance. Also, update the audit log data set name if you are using this feature.
  • Create a copy of the MFAS proc in the proclib data set and update the JCL EXEC statement PARM field to specify the new MFAS ACBNAME in the APPLID= parameter. Also, update the VSAMCTL DD statement data set name if you want to allocate and manage a different set of mapping members for this instance.
  • Update the SERVERS definition for the new instance with the name of the new proc that was created from the MFAS proc (that is, update the ASPROC=MFAS value).
Parent topic: Configuration


Administration Using Console Commands

This section describes the console commands available for administering Mainframe Access.

  • Introduction
  • Console Commands
  • Using a Telnet Client
Parent topic: Configuring and Administering the Mainframe


Introduction

Mainframe Access provides a number of console commands that you can use to control execution and display the operational status of Mainframe Access. To use these commands, you must be authorized to use z/OS system console commands. Most of the commands are variants of the z/OS Modify (F) command, with the general format:

F your-procedure-name,command-text

where the parameters are:

your-procedure-name | The name of your Mainframe Access startup JCL as explained in the section Mainframe Access Data Sets in the chapter Configuration
command-text | One of the commands described in the section Console Commands

You use the z/OS Start (S) command to start Mainframe Access:

S your-procedure-name

You use the z/OS Stop (P) command to stop Mainframe Access:

P your-procedure-name

You can enter the commands in any of the following ways:

  • From an z/OS system console
  • Using an interface that allows the entry of z/OS system commands, such as IBM's TSO/ISPF SDSF (System Display and Search Facility)
  • Using a Telnet client through an Internet connection. You cannot start or stop Mainframe Access using a Telnet client. For more information on using a Telnet client see the section Using a Telnet Client

You can also control and monitor the operation of Mainframe Access through a Web browser interface that offers functionality in addition to that provided by the console commands. For further information on the Web browser interface see the chapter Administration Using the Web Interface.

Parent topic: Administration Using Console Commands
Related information
Mainframe Access Data Sets
Console Commands
Using a Telnet Client


Console Commands

All the available console commands are described in this section.

  • Start
  • Stop
  • TRACE ON and TRACE SHORT
  • REFRESH ACCESSLIST
  • DISPLAY LU
  • DISPLAY TCPSTATUS
  • DISPLAY CONVERSATION
  • C CONV=id
  • FLUSH XDBOUT
  • RESET TIMEOUT=n
  • SET TIMEOUT=n
Parent topic: Administration Using Console Commands


Start

Starts the Mainframe Access task. Mainframe Access automatically starts the Mainframe Access Data Connect server, MFAS, during initialization.

Here is an example of a Start command and the response:

15:49:32.45 CSIRLW1  00000290  S MFA
15:49:32.47 STC05579 00000090  $HASP100 MFA ON STCINRDR
15:49:32.55 STC05579 00000290  IEF695I START MFA WITH JOBNAME MFA IS ASSIGNED TO USER RWITEK, GROUP DEVELOP
15:49:32.55 STC05579 00000090  $HASP373 MFA  STARTED
15:49:32.55 STC05579 00000090  IEF403I MFA - STARTED - TIME=15.49.32
15:49:32.85 STC05579 00000090  MFM0014I: Mainframe Access V3.01 (ga) for YOUR_COMPANY_NAME
15:49:32.85 STC05579 00000090  MFM0066I: Address space type is CTLRGN
15:49:32.86 STC05579 00000090  MFM0057I: GTF user record id (eid) is 00E9
15:49:32.86 STC05579 00000090  MFM0012I: TCP port number is 1503
15:49:32.86 STC05579 00000090  MFM0013I: Admin port number is 1504
15:49:32.86 STC05579 00000090  MFM0047I: DSS maximum shared public files is 10
15:49:32.86 STC05579 00000090  MFM0055I: DSS scan interval is 2 minutes
15:49:32.86 STC05579 00000090  MFM0054I: SMF recording is off, record id is zero or invalid
15:49:32.87 STC05579 00000090  MFM0063I: MFA Direct is active
15:49:32.87 STC05579 00000090  MFM0064I: MFA Direct number of processing tasks is 5
15:49:33.16 STC05579 00000090  MFMDS052I CA/PanValet Ready
15:49:33.21 STC05579 00000090  MFMDS055I MCG/RPC feature inactive
15:49:33.22 STC05579 00000090  MFMDS001I DSS Server Ready
15:49:36.92 STC05579 00000090  MFM0001I: Mainframe Access V3.01 (ga) is active
15:49:37.00 STC05580 00000090  $HASP100 MFAS ON STCINRDR
15:49:37.06 STC05580 00000090  $HASP373 MFAS  STARTED
15:49:37.06 STC05580 00000090  IEF403I MFAS - STARTED - TIME=15.49.37
15:49:37.23 STC05580 00000090  MFA302I.MFAS.MFARSC00 / ATTACHING VTAM PROCESSOR
15:49:37.24 STC05580 00000090  MFA303I.MFAS.MFARSC00 / MFA/MVS V3.01 - PTF 2001PTF6 COPYRIGHT (C)
                               1987-2003 MICRO FOCUS INTERNATIONAL LTD.
15:49:37.24 STC05580 00000090  MFA110I.MFAS.MFAFSQ00 / VTAM PROCESSOR ACTIVE USING VTAMAPPL MFA62ACB
Parent topic: Console Commands


Stop

Stops the Mainframe Access task. Mainframe Access automatically stops the Mainframe Access Data Connect server, MFAS, during shutdown. Shutdown may take anywhere from 30 seconds to a few minutes, depending on the level of activity in the system.

Here is an example of a Stop command and the response:

16:44:18.52 CSIRLW1  00000290  P MFA
16:44:21.52 STC05579 00000290  P MFAS
16:44:21.53 STC05580 00000090  MFA112I.MFAS.MFAFSQ00 / VTAM PROCESSOR HAS TERMINATED
16:44:21.68 STC05580 00000090  MFA317I.MFAS.MFARSC00 / HAS BEEN TERMINATED
16:44:21.69 STC05579 00000090  MFMDS005I DSS Server shutdown
16:44:21.70 STC05580 00000090  IEF404I MFAS - ENDED - TIME=16.44.21
16:44:21.70 STC05580 00000090  $HASP395 MFAS  ENDED
16:44:32.77 STC05579 00000090  MFM0011I: Mainframe Access shutdown completed
16:44:32.82 STC05579 00000090  IEF404I MFA - ENDED - TIME=16.44.32
16:44:32.82 STC05579 00000090  $HASP395 MFA  ENDED
Parent topic: Console Commands


TRACE ON and TRACE SHORT

Activates detailed tracing of all Mainframe Access activity. Trace output is directed to the destination (SYSPRINT, GTF or CONSOLE) specified by the TRACE parameter during Mainframe Access startup. For more information about these options see the entry for the TRACE parameter in the section Editing Mainframe Access Parameters in the chapter Configuration. For a tip about viewing trace data sent to SYSPRINT interactively see the FLUSH XDBOUTcommand description

Here is an example of a TRACE ON command and the response:

F MFA,TRACE ON
MFM0015I: MFM0025I: Trace set to data level on

The TRACE SHORT command activates the same detailed tracing as does the TRACE ON command. The SHORT option limits the display of send data, receive data and storage areas to 256 characters. This can be useful in reducing the amount of trace output, particularly when the message sizes are large.

Here is an example of a TRACE SHORT command and the response:

F MFA,TRACE SHORT
MFM0015I: MFM0025I: Trace set to data level on
Parent topic: Console Commands
Related information
Editing Mainframe Access Parameters
FLUSH XDBOUT


REFRESH ACCESSLIST

Directs Mainframe Access to re-read the access list from the currently active access list data set (the access list identified by the //XDBACC DD statement in the Mainframe Access startup JCL). You can update the access list by adding, removing or updating PERMIT, REJECT and ADMUSER lines, as described in the section Editing Access List Definitions in the chapter Configuration. When your updates are complete, use REFRESH ACCESSLIST to replace the currently active access list with your updated list without stopping and restarting Mainframe Access.

Here is an example of a REFRESH ACCESSLIST command and the response:

F MFA,REFRESH ACCESSLIST
MFM0015I: Refresh Access List has completed
Parent topic: Console Commands
Related information
Editing Access List Definitions


DISPLAY LU

Displays information about the target servers which Mainframe Access has successfully connected to by establishing one or more LU6.2 sessions in response to client requests. Target servers are known to Mainframe Access by their SNA LU name or APPLID.

Here is an example of a DISPLAY LU command and the resulting display:

F MFA,DISPLAY LU
MFM0015I:  ***************************************************
MFM0015I:  *                   PLU Status                    *
MFM0015I:  ***************************************************
MFM0015I:
MFM0015I:  ******* Partner LU Status
MFM0015I:  LU Name..........LUDB27R
MFM0015I:     Mod Entry........IBMRDB
MFM0015I:     Status...........Active
MFM0015I:  LU Name..........MFA62ACB
MFM0015I:     Mod Entry........#INTER
MFM0015I:     Status...........Active
Parent topic: Console Commands


DISPLAY TCPSTATUS

Displays basic TCP/IP configuration information from the Mainframe Access parameters (port number, company name and connection backlog) followed by the information displayed by the DISPLAY LU and DISPLAY CONVERSATION commands.

Here is an example of a DISPLAY TCPSTATUS command and the resulting display:

F MFA,DISPLAY TCPSTATUS
MFM0015I:  ***************************************************
MFM0015I:  *                   TCP Status                    *
MFM0015I:  ***************************************************
MFM0015I:
MFM0015I:  Server Port Number.......1503
MFM0015I:  Web Server Port Number...1504
MFM0015I:  OID....................YOUR_COMPANY_NAME
MFM0015I:  Number of Backlogs.......5
MFM0015I:  ******* Partner LU Status
MFM0015I:  LU Name..........LUDB27R
MFM0015I:     Mod Entry........IBMRDB
MFM0015I:     Status...........Active
MFM0015I:  LU Name..........MFA62ACB
MFM0015I:     Mod Entry........#INTER
MFM0015I:     Status...........Active
MFM0015I:  ******* Conversation Status
MFM0015I:  Conversation ID..1AA14028
MFM0015I:     Conv Address.....1AC79968
MFM0015I:     Alloc Address....1A928DC0
MFM0015I:     Task Address.....1AA4CE28
MFM0015I:     Conv Status......Active
MFM0015I:     TCP/IP Status....Send
MFM0015I:     User Id..........CSIRLW1
MFM0015I:     Target LU........LUDB27R
MFM0015I:     Peer IP address..10.10.11.130
MFM0015I:     Socket Number....9
MFM0015I:     Start Time.......07/17/03 15:10:32
MFM0015I:     LUW Id...........DDINE.MFM62ACB.B9BBC4F618400001
MFM0015I:     Packets Sent.....14
Parent topic: Console Commands
Related information
DISPLAY LU
DISPLAY CONVERSATION


DISPLAY CONVERSATION

Displays detailed information about every active conversation between Mainframe Access and the target servers.

Here is an example of a DISPLAY CONVERSATION command and the resulting display:

F MFA,DISPLAY CONVERSATION
MFM0015I:  ***************************************************
MFM0015I:  *               Conversation Status               *
MFM0015I:  ***************************************************
MFM0015I:
MFM0015I:  ******* Conversation Status
MFM0015I:  Conversation ID..1AA14028
MFM0015I:     Conv Address.....1AC79968
MFM0015I:     Alloc Address....1A928DC0
MFM0015I:     Task Address.....1AA4CE28
MFM0015I:     Conv Status......Active
MFM0015I:     TCP/IP Status....Send
MFM0015I:     User Id..........CSIRLW1
MFM0015I:     Target LU........LUDB27R
MFM0015I:     Peer IP address..10.10.11.130
MFM0015I:     Socket Number....9
MFM0015I:     Start Time.......07/17/03 15:10:32
MFM0015I:     LUW Id...........DDINE.MFM62ACB.B9BBC4F618400001
MFM0015I:     Packets Sent.....14
MFM0015I:     Packets Rcv'd....27
MFM0015I:  Conversation ID..1ABFF2E0
MFM0015I:     Conv Address.....1ACD0968
MFM0015I:     Alloc Address....1A928BA0
MFM0015I:     Task Address.....1AA4CA78
MFM0015I:     Conv Status......Active
MFM0015I:     TCP/IP Status....Send
MFM0015I:     User Id..........CSIRLW1
MFM0015I:     Target LU........MFA62ACB
MFM0015I:     Peer IP address..10.10.11.130
MFM0015I:     Socket Number....13
MFM0015I:     Start Time.......07/17/03 15:11:40
MFM0015I:     LUW Id...........DDINET1.MFM62ACB.B9BBC538B9410001
MFM0015I:     Packets Sent.....4
Parent topic: Console Commands


C CONV=id

Cancels a specific conversation. Theid parameter is a conversation identifier of eight hexadecimal characters as shown in the information displayed by DISPLAY CONVERSATION and DISPLAY TCPSTATUS commands. Canceling a conversation ends the LU6.2 conversation to the target server and releases the LU6.2 session for use by other conversations. It also disconnects the client by closing the client socket associated with the conversation and cancels the DDF thread if the conversation partner is DB2.

Here is an example of the CANCEL CONVERSATION command that cancels the second conversation shown in the DISPLAY CONVERSATION example:

F MFA,C CONV=1ABFF2E0
MFM0015I: Cancel Command accepted
Parent topic: Console Commands


FLUSH XDBOUT

Flushes trace data and operational messages to the //XDBOUT DD SYSOUT data set. Operational data is written to XDBOUT during normal operation; trace data is written to XDBOUT only when tracing is switched on and the trace destination is SYSPRINT. The FLUSH command causes any partially filled buffer to be written to the SYSOUT data set, making the output available for browsing. This can be helpful when you are testing and trying to view trace data interactively as the test progresses.

Here is an example of a FLUSH XDBOUT command and the response:

F MFA,FLUSH XDBOUT
MFM0015I: Flush XDBOUT completed
Parent topic: Console Commands


RESET TIMEOUT=n

Changes the TIME OUT FOR CONNECTION parameter value without you having to stop and restart Mainframe Access. The n parameter is the number of minutes that a client connection can remain idle before the connection will be broken and Mainframe Access resources dedicated to the client will be released. Resources that are released when an idle client is disconnected include allocated storage, TCP/IP resources and LU6.2 conversations to target servers such as DB2, IMS, CICS and Mainframe Access Data Connect. Specify 0 (zero) to disable the client timeout feature and allow unlimited idle time.

If you use the RESET TIMEOUT command to establish a new timeout value, rather than SET TIMEOUT, both the Mainframe Access timeout and any Mainframe Access client timeout remain in effect. The connection partner (Mainframe Access client or Mainframe Access) having the smaller timeout value initiates the disconnection first.

Here is an example of a RESET TIMEOUT command and the response:

F MFA,RESET TIMEOUT=30
MFM0015I: Timeout parameter reset to 30
Parent topic: Console Commands


SET TIMEOUT=n

Changes the TIME OUT FOR CONNECTION parameter value without you having to stop and restart Mainframe Access. The n parameter is the number of minutes that a client connection can remain idle after which the connection will be broken and Mainframe Access resources dedicated to the client will be released. Resources that are released when an idle client is disconnected include allocated storage, TCP/IP resources and LU6.2 conversations to target servers such as DB2, IMS, CICS and Mainframe Access Data Connect. Specify 0 (zero) to disable the client timeout feature and allow unlimited idle time.

If you use the SET TIMEOUT command to establish a new timeout value, rather than RESET TIMEOUT, then when a Mainframe Access client subsequently starts up, Mainframe Access' connection timeout is disabled, and only the inactivity timeout period specified by the Mainframe Access client is in effect.

Here is an example of a SET TIMEOUT command and the response:

F MFA,SET TIMEOUT=20
MFM0015I: Timeout parameter set to 20
Parent topic: Console Commands


Using a Telnet Client

This section describes how to connect to Mainframe Access using a Telnet client, enter commands and disconnect.

  • Connecting to Mainframe Access using a Telnet Client
  • Entering Commands from a Telnet Client
  • Disconnecting from a Telnet Client
Parent topic: Administration Using Console Commands


Connecting to Mainframe Access using a Telnet Client

To connect to Mainframe Access using Telnet, follow these steps:

  1. Start your Telnet client software.
  2. Click Remote System on the Connect menu.
  3. In the Connect dialog box, fill in the fields as follows:
    Host Name | TCP/IP host name of your z/OS system
    Port | The value in the Mainframe Access start-up parameter TCP_PORT
    TermType | A suitable terminal type emulation for your connection, such as VT100
  4. Click Connect.

An example is shown below.

Figure 1. Telnet Connect Dialog Box
Telnet Connect Dialog Box

After the connection is established, press Enter twice. This is essential to enable Mainframe Access to recognize the Telnet client, since Mainframe Access uses the same port for several different types of client connection. When Mainframe Access recognizes the Telnet client it sends out an initial prompting message and is ready to receive commands.

Parent topic: Using a Telnet Client


Entering Commands from a Telnet Client

You can enter any console command except Start and Stop by prefixing the command string with a single dollar sign ($). Mainframe Access responds by displaying the command output data followed by the prompting message to indicate readiness for another command. Figure 3-2 shows the command input line $display tcpstatus and the resulting command output data.

Figure 1. Entering a Command
Entering a Command
Parent topic: Using a Telnet Client


Disconnecting from a Telnet Client

To disconnect from a Telnet client, either:

  • Shut down your Telnet client software
  • Enter the "end" command with no dollar sign prefix
Parent topic: Using a Telnet Client


Troubleshooting

This chapter contains information that will help you to diagnose software problems related to Mainframe Access.

  • Abend Codes
  • LU6.2 Diagnostic Information
  • Mainframe Access Host Error Codes
  • Mainframe Access Remote IMS Error Codes
  • IBM SAF and RACF Error Codes
  • Mainframe Access Audit Report Program
  • Obtaining a VTAM Buffer Trace
Parent topic: Configuring and Administering the Mainframe


Abend Codes

An abend, or abnormal end, is the most obvious way for a software problem to be indicated. The z/OS processing for an abend normally creates a dump of the failing program's address space storage for use in problem determination. An abend can be initiated by Mainframe Access itself or by other software components of the z/OS system. Although a program abend is most often the result of a software error within the failing program, abend conditions can also be caused by other software and hardware components of the system.

  • System Abend Codes
  • Mainframe Access User Abend Codes
Parent topic: Troubleshooting


System Abend Codes

Many software failures are detected by z/OS and its components. These conditions are normally reported as system abends using a code consisting of the letter S identifying a system abend and three hexadecimal digits, for example, S0C4. Complete descriptions of these conditions can found in the IBM publications for your specific version of z/OS. If a system abend is reported for Mainframe Access, it is important to review the abend description. This will help you to make an initial determination as to whether this is most likely a Mainframe Access program failure or a failure caused by other system conditions that have affected the execution of Mainframe Access.

Parent topic: Abend Codes


Mainframe Access User Abend Codes

When Mainframe Access detects a condition that prevents the program from continuing, it requests z/OS to begin abend processing for a user abend. Many of these conditions are detected by Mainframe Access initialization or by the item library format utility. z/OS reports user abends using a code consisting of the letter U identifying a user abend and four decimal digits, for example, U2111. The user abend codes that can be issued by Mainframe Access and recommended actions are listed in the following table.

User Abend Code | Description of Cause | Recommended Action
99 | Issued when a Data Set Services ISPI module cannot determine the invocation reason. | Contact our Product Support.
801 | Processing to establish or remove a Mainframe Access ESTAEX error recovery routine has failed. | Contact our Product Support.
996 | The MFA Server DSS Services component failed to initialize properly. This is a should not occur condition. | Contact our Product Support.
997 | An Endevor error has occurred in the application server address space. Common causes include a general setup failure, MSGLOG allocation failure, or the Endevor C1DEFLTS module could not be found. Endevor requests cannot be processed. | Examine the joblog and syslog for system messages and server messages that can help identify the specific error. Contact our Product Support if you are unable to resolve the problem
998 | There is a difference between the Endevor support modules available to the MFA Server control region and the Endevor support modules available in the MFA Server application server region(s). Different versions of Endevor are being referenced by the regions. Endevor requests cannot be processed. | This is most likely caused by differences in the STEPLIB or JOBLIB concatenations in the JCL used to start the regions. Contact our Product Support if you are unable to resolve the problem.
999 | This abend code indicates that the Endevor support modules are not available to MFA Server. Endevor requests cannot be processed. | The Endevor AUTHLIB and CONLIB data sets must be included in the MFA started task JCL (for both the control region and the application server regions) or these data sets must be available in the standard system LNKLST specifications. Contact our Product Support if you are unable to resolve the problem.
2100 | Processing to establish or remove a Mainframe Access ESTAEX error recovery routine has failed. | Contact our Product Support.
3100 | Processing associated with Mainframe Access' dependent addresss space services has encountered a should not occur condition. | Contact our Product Support.
3101 | Work order allocation for a dependent address space service has failed. This is a should not occur condition. | Contact our Product Support.
3102 | Allocation for a dependent address space service program call block has failed. This is a should not occur condition. | Contact our Product Support.
3103 | Work order queuing for a dependent address space service has failed. This is a should not occur condition. | Contact our Product Support.
Parent topic: Abend Codes


LU6.2 Diagnostic Information

Mainframe Access uses IBM's VTAM APPCCMD interface for LU6.2 communication with many of the target server systems, such as CICS, IMS and DB2. When problems arise and an error is reported for LU6.2 communication with one of these systems, the exact conditions of the error are indicated to Mainframe Access as return values from the APPCCMD call. These return values are logged to Mainframe Access' XDBOUT SYSOUT data set and can help you to identify and correct the situation. The following tables summarize the return value information. If you need more information, see the z/OS Communications Server SNA Programmer's LU 6.2 Reference manual for your level of z/OS and VTAM.

  • RTNCD and FDB2 Return Values for LU6.2 APPCCMD Calls
  • RCPRI and RCSEC Return Values for LU6.2 APPCCMD Calls
Parent topic: Troubleshooting


RTNCD and FDB2 Return Values for LU6.2 APPCCMD Calls

The RTNCD (return code) and FDB2 (feedback two) values are the major return values associated with an APPCCMD call. The following table summarizes these major return values.

RTNCD | FDB2 | Explanation
X'00' | X'0B' | An error occurred during the execution of the APPCCMD call. The specific nature of the error is indicated by secondary return values, RCPRI and RCSEC, as documented in the next section
X'04' | X'05' | Symbolic name known by network-qualified name only
X'10' | X'13' | Attempt to start 6.2 session: request rejected
X'10' | X'14' | Attempt to start 6.2 session: pending session terminated
X'10' | X'15' | An APPCCMD must be issued
X'14' | X'7F' | Policing error: non-APPC macro
Parent topic: LU6.2 Diagnostic Information


RCPRI and RCSEC Return Values for LU6.2 APPCCMD Calls

The RPL extension contains two fields in which return code information is passed to the application program at the completion of an LU6.2 APPCCMD macroinstruction execution. The RCPRI field returns a primary return code to the application; the RCSEC field returns a secondary return code to the application.

RCPRI | RCSEC | Explanation
X'0000' | X'0000' | OK; no errors
X'0000' | X'0001' | As specified; CNOS values were accepted
X'0000' | X'0002' | As negotiated; CNOS values changed by negotiation
X'0000' | X'0003' | Receive specific rejected
X'0000' | X'0004' | Partner LU supports single session
X'0000' | X'0005' | Internal VTAM error
X'0000' | X'0006' | Restore unnecessary; no modes to restore
X'0000' | X'0007' | Restore complete; input work area too small
X'0000' | X'0008' | No immediately available information
X'0000' | X'0009' | Request terminated by end of conversation
X'0000' | X'000A' | Sessions will use appl name, generic name requested
X'0000' | X'000B' | Sessions will use generic name, appl name requested
X'0000' | X'000C' | As specified, partner LU known by different name
X'0000' | X'000D' | As negotiated, partner LU known by different name
X'0004' | ALL | Allocation error
X'0004' | X'0000' | Allocation failure no retry
X'0004' | X'0001' | Allocation failure retry
X'0004' | X'0002' | Conversation type mismatch
X'0004' | X'0003' | PIP not allowed
X'0004' | X'0004' | PIP not specified correctly
X'0004' | X'0005' | Security not valid
X'0004' | X'0006' | Sync level not supported by LU
X'0004' | X'0007' | Sync level not supported by program
X'0004' | X'0008' | Transaction program name (TPN) not recognized
X'0004' | X'0009' | Transaction program name (TPN) not available; no retry
X'0004' | X'000A' | Transaction program name (TPN) not available; retry
X'0004' | X'000B' | Cannot reconnect transaction program; no retry
X'0004' | X'000C' | Cannot reconnect transaction program; retry
X'0004' | X'000D' | Reconnect not supported by program
X'0004' | X'000E' | Mode must be restored before using
X'0004' | X'000F' | Deallocation requested
X'0004' | X'0010' | Allocation error - sync level not valid for full duplex
X'0004' | X'0011' | Allocation error - LU pair not supporting FDX conversation
X'0008' | ALL | CNOS failure
X'0008' | X'0000' | Allocation failure; retry
X'0008' | X'0001' | Allocation failure; no retry
X'0008' | X'0002' | Transaction program not available; retry
X'0008' | X'0003' | Transaction program not available; no retry
X'0008' | X'0004' | Conversation type mismatch
X'0008' | X'0005' | Security not valid
X'0008' | X'0006' | Mode must be restored before using
X'0008' | X'0007' | Network qualified name mismatch
X'000C' | X'0000' | CNOS resource failure; no retry
X'0010' | X'0000' | Partner granted retry
X'0010' | X'0001' | Control operator for local LU retried
X'0010' | X'0002' | Partner CNOS in progress
X'0010' | X'0003' | LU in pending single state
X'0010' | X'0004' | Partner LU starting session
X'0014' | X'0000' | Deallocate abend program
X'0018' | X'0000' | Deallocate abend service
X'001C' | X'0000' | Deallocate abend timer
X'0020' | X'0000' | CNOS failure; retry
X'0024' | X'0000' | Logical record boundary error
X'0028' | X'0000' | LU mode session limit closed
X'002C' | ALL | Parameter error
X'002C' | X'0000' | Invalid LU name or network identifier
X'002C' | X'0001' | Invalid mode
X'002C' | X'0002' | Invalid conversation
X'002C' | X'0003' | Invalid LL
X'002C' | X'0004' | Invalid values for SNASVCMG mode
X'002C' | X'0005' | Invalid DRAINL change
X'002C' | X'0006' | SNASVCMG mode cannot currently be reset
X'002C' | X'0007' | MINWINL plus MINWINR exceeds SESSLIM
X'002C' | X'0008' | Supplied length insufficient
X'002C' | X'0009' | Incomplete structure supplied
X'002C' | X'000A' | Incomplete FMH5 supplied
X'002C' | X'000B' | Incomplete GDS variable supplied
X'002C' | X'000C' | Zero EXIT field
X'002C' | X'000D' | Zero ECB field
X'002C' | X'000E' | Request invalid for address space
X'002C' | X'000F' | Control block invalid
X'002C' | X'0010' | Invalid data address or length
X'002C' | X'0011' | Previous macroinstruction outstanding
X'002C' | X'0012' | Buffer list length invalid
X'002C' | X'0013' | No corresponding mode in LM table
X'002C' | X'0014' | Invalid BIND parameters
X'002C' | X'0015' | Invalid TPN
X'002C' | X'0016' | No corresponding LU in LM table
X'002C' | X'0017' | Invalid mode specified
X'002C' | X'0018' | Invalid limit specified
X'002C' | X'0019' | SNASVCMG mode already initialized
X'002C' | X'001A' | All modes specified on single session LU
X'002C' | X'001B' | SNASVCMG or CPSVCMG mode for single session LU
X'002C' | X'001C' | Single session, mode already initialized
X'002C' | X'001E' | CID invalid
X'002C' | X'001F' | APPCCMD issued for non-APPC
X'002C' | X'0020' | Previous REJECT request outstanding
X'002C' | X'0021' | Abnormal deallocate rejected; retry
X'002C' | X'0022' | Invalid CONTROL or QUALIFY value
X'002C' | X'0023' | Invalid session instance identifier
X'002C' | X'0024' | PS header not supplied
X'002C' | X'0025' | PS header length is insufficient
X'002C' | X'0026' | Session instance identifier and conversation identifier mismatch
X'002C' | X'0027' | Invalid deactivation type code
X'002C' | X'0028' | Cryptography not allowed on mode
X'002C' | X'0029' | Invalid LIST value specified on APPCCMD for restore
X'002C' | X'002A' | Invalid CGID value specified
X'002C' | X'002B' | Network-qualified name required
X'002C' | X'002C' | Parameter error; invalid expedited data length
X'002C' | X'002D' | Parameter error; invalid sense code value specified
X'002C' | X'002E' | Vector area not valid
X'002C' | X'002F' | Vector area length insufficient
X'002C' | X'0030' | Parameter error; storage type not valid
X'002C' | X'0031' | Parameter error; SENDRCV specified with OPTCD=BUFFLST/XBUFLST
X'002C' | X'0032' | Parameter error; unexpected vector provided on APPCCMD
X'002C' | X'0033' | Parameter error; required vector not provided or incorrect
X'002C' | X'0034' | Password substitution value set in error
X'0030' | X'0000' | Program error; no truncation
X'0034' | X'0000' | Program error purging
X'0038' | X'0000' | Program error truncating
X'003C' | X'0000' | Service error; no truncation
X'0040' | X'0000' | Service error purging
X'0044' | X'0000' | Service error truncating
X'0048' | X'0000' | Resource failure; no retry
X'004C' | X'0000' | Resource failure; retry
X'0050' | X'0000' | State error
X'0054' | X'0000' | Unrecognized mode name
X'0058' | X'0000' | Unsuccessful; session not available
X'005C' | ALL | User error code received
X'005C' | X'0000' | Following negative response
X'005C' | X'0001' | Without negative response
X'0060' | X'0000' | No FMH5 available
X'0064' | X'0000' | Activation failure
X'0068' | X'0000' | LU mode session limit exceeded
X'006C' | X'0000' | Session not pending
X'0070' | X'0000' | Temporary storage shortage or resource shortage
X'0074' | X'0000' | Halt issued
X'0078' | X'0000' | VTAM inactive for your ACB
X'007C' | X'0000' | Request aborted
X'0080' | X'0000' | Deallocate normal
X'0084' | X'0000' | Storage shortage
X'0088' | X'0000' | Canceled by reject or abnormal deallocate
X'008C' | X'0000' | Partner committed protocol violation
X'0090' | X'0000' | Application not APPC capable
X'0094' | X'0000' | Invalid condition for sending data
X'0098' | X'0000' | Temporary storage shortage while sending data
X'009C' | X'0000' | Restore rejected - restore issued before SETLOGON start
X'00A0' | ALL | Request not allowed
X'00A0' | X'0001' | LU pair does not support sending expedited data
X'00A0' | X'0002' | Request blocked
X'00A0' | X'0003' | Execution of request terminated
X'00A0' | X'0004' | CONTROL/QUALIFY value invalid for full-duplex conversation
X'00A0' | X'0005' | Response has not been received for a previous SENDEXPD request
X'00A0' | X'0006' | Program not authorized for requested function
X'00A4' | X'0000' | Mode must be restored before using
X'00A8' | ALL | Environment error
X'00A8' | X'0000' | OS level does not support request function
X'00A8' | X'0001' | Suspend failure
X'00A8' | X'0002' | Resume failure
X'00AC' | ALL | Error indication received
X'00AC' | X'0001' | Deallocate abend program
X'00AC' | X'0002' | Deallocate abend service
X'00AC' | X'0003' | Deallocate abend time
X'00AC' | X'0004' | Allocation error
X'00AC' | X'0005' | Unknown error code
X'00AC' | X'0006' | Resource failure; retry
X'00AC' | X'0007' | Resource failure; no retry
X'00B0' | ALL | Name resolution error
X'00B0' | X'0001' | LU name found in a variant name entry
X'00B0' | X'0002' | Name returned differs from associated name
X'00B0' | X'0003' | Name returned found in variant name entry
X'00B0' | X'0004' | Name returned found in supplied name entry
X'00B0' | X'0005' | Partner network name mismatch
X'00B0' | X'0006' | LU name found in an unusable name entry
X'00B0' | X'0007' | Name returned found in an unusable name entry
X'00B0' | X'0008' | LU name found in a disassociated name entry
X'00B4' | ALL | CSM detected error
X'00B4' | X'0001' | CSM detected error - not specified
X'00B4' | X'0002' | CSM detected error - invalid buffer token specified
X'00B4' | X'0003' | CSM detected error - invalid instance id specified
Parent topic: LU6.2 Diagnostic Information


Mainframe Access Host Error Codes

The return code and reason code values documented in the following table may appear in error responses sent from Mainframe Access to client products.

Return Code | Reason Code | Explanation | Action
X'00000008' | X'00000001' | XERROR_ALLOC The LU6.2 session allocation failed. | Check the target DB2 APPLID or MODNAME.
X'00000008 | X'00000002' | XERROR_ALLOC The LU6.2 session allocation failed without a conversation block. | Check the APPLID and MODNAME for the target DB2.
X'00000009' | X'00000001' | XERROR_INVALIDPACKET An invalid packet type; the correct packet is an allocation packet. | Check the client program.
X'00000009' | X'00000002' | XERROR_INVALIDPACKET An invalid packet type; the correct packet is a dellocation data packet. | Contact our Product Support.
X'00000010' | X'FFFFFFFF' | XERROR_SEND The maximum number of concurrent users was reached. | Contact a Micro Focus sales representative to purchase more seats for your license.
X'00000011' | X'00000001' | XERROR_RECEIVE The LU6.2 session failed in the receive mode. | Contact our Product Support.
X'00000013' | X'00000001' | XERROR_FUNCTIONNOTALLOWED The IMS/VSAM access feature is not available at your site. | Contact a Micro Focus sales representative to purchase a license for this feature.
X'00000013' | X'00000002' | XERROR_FUNCTIONNOTALLOWED The PEM feature is not available at your site. | Contact a Micro Focus sales representative to purchase a license for this feature.
X'00000014' | X'00000001' | XERROR_INVALIDTRAN The transaction type in the first packet is invalid. | Contact our Product Support.
X'00000015' | X'00000001' | XERROR_CONV The LU6.2 session lost the conversation control block. | Contact our Product Support.
X'00000017' | X'00000rpl' | XERROR_SENDRPL The LU6.2 session failed with the RPL code in the reason code block. | Contact our Product Support.
X'00000018' | X'00000rpl' | XERROR_RECEIVERPL The LU6.2 session failed in receive mode with the RPL code in the reason code block. | Contact our Product Support.
X'00000100' | X'00000100' | XERROR_INTERNAL Unknown request type. | Contact our Product Support.
Parent topic: Troubleshooting


Mainframe Access Remote IMS Error Codes

Return Code | Reason Code | Description of Cause | Action
400 | Bad request type | TYPE=ALLOCERR: Request type is invalid | The first packet's request type must be ALLOC. Resubmit an ALLOC packet.
400 | Bad request, ID block is missing | TYPE=ALLOCERR: Mainframe Access does not have the configuration for the IMSID | Check the IMSID and resubmit.
505 | Version not supported | TYPE=ALLOCERR: The client is not supported by Mainframe Access | Contact our Product Support.
602 | IMS Applid is not valid | TYPE=ALLOCERR: Either IMS is not available or IMS/APPC is not enabled. | Contact our Product Support.
604 | IMS Alloc Failure, RC = rc | TYPE=ALLOCERR: Routine failed to initiate a conversation with the target IMS system. rc is the decimal number of the return code from VTAM. | Contact our Product Support.
606 | Receive Error | TYPE=RPL,CODE=rc: Conversation to IMS has failed during a receive operation with RPL code. rc is the return code. The first two bytes are the RPL primary code; the next two bytes are the RPL secondary code. | Check the entries, correct any errors, and resubmit request.
606 | Send Error | TYPE=RPL,CODE=rc: Conversation to IMS has failed during a send operation with RPL code. The first two bytes are the RPL primary code; the next two bytes are the RPL secondary code. | Check the entries, correct any errors, and resubmit request.
606 | LU6.2 Error | TYPE=RPL,CODE=rc: Conversation to IMS has failed with RPL code. The first two bytes are the RPL primary code; the next two bytes are the RPL secondary code. | Check the entries, correct any errors, and resubmit request.
613 | Userid/Password Required | TYPE=ALLOCERR: Security is enforced in the configuration and user ID or password in the request packet is missing. | Check and correct user ID and password and resubmit request packet.
699 | Mainframe Access HTTP Parsing Error | TYPE=ALLOCERR: The input HTTP packet has invalid record or format. | Check the record or format of the HTTP packet and resubmit.
Parent topic: Troubleshooting


IBM SAF and RACF Error Codes

The return code and reason code values documented in the following table may appear in error messages associated with z/OS security subsystem request failures.

  • Error Codes for VERIFY Requests
  • Error Codes for AUTH Requests
Parent topic: Troubleshooting


Error Codes for VERIFY Requests

The return code and reason code values documented in the following table are associated with RACROUTE REQUEST=VERIFY requests that are issued to authenticate a user based on the userid and password that were submitted.

SAF Return Code | RACF Return Code | RACF Reason Code | Description
X'00' | X'00' | X'0000' | Request completed successfully.
X'00' | X'04' | X'000C' | Request completed successfully. TOKNIN was specified but the length was too large.
X'00' | X'04' | X'0010' | Request completed successfully. STOKEN was specified but the length was too large.
X'04' | X'00' | X'0000' | Request could not be completed. No RACF decision was possible. ENVIR=VERIFY was specified without SAF installation exit processing.
X'04' | X'04' | X'0000' | Request could not be completed. No RACF decision was possible. The user profile is not defined to RACF.
X'04' | X'20' | X'0000' | Request could not be completed. No RACF decision was possible. RACF is not active.
X'04' | X'58' | X'0000' | Request could not be completed. No RACF decision was possible. RJE or NJE operator FACILITY class profile not found.
X'08' | X'04' | X'0000' | Request failed. The user profile is not defined to RACF.
X'08' | X'08' | X'0000' | Request failed. The password is not authorized.
X'08' | X'0C' | X'0000' | Request failed. The password has expired.
X'08' | X'10' | X'0000' | Request failed. The new password is not valid.
X'08' | X'14' | X'0000' | Request failed. The user is not defined to the group.
X'08' | X'18' | X'0000' | Request failed. RACROUTE REQUEST=VERIFY was failed by the installation exit routine.
X'08' | X'1C' | X'0000' | Request failed. The user's access has been revoked.
X'08' | X'24' | X'0000' | Request failed. The user's access to the specified group has been revoked.
X'08' | X'28' | X'0000' | Request failed. OIDCARD parameter is required but not supplied.
X'08' | X'2C' | X'0000' | Request failed. OIDCARD parameter is not valid for specified user.
X'08' | X'30' | X'0000' | Request failed. The user is not authorized to the port of entry in the TERMINAL, JESINPUT, or CONSOLE class. Indicates the user is not authorized to the port of entry.
X'08' | X'30' | X'0004' | Request failed. The user is not authorized to the port of entry in the TERMINAL, JESINPUT, or CONSOLE class. Indicates the user is not authorized to access the system on this day, or at this time of day.
X'08' | X'30' | X'0008' | Request failed. The user is not authorized to the port of entry in the TERMINAL, JESINPUT, or CONSOLE class. Indicates the port of entry may not be used on this day, or at this time of day.
X'08' | X'34' | X'0000' | Request failed. The user is not authorized to use the application.
X'08' | X'38' | X'0004' | Request failed. SECLABEL checking failed. MLACTIVE requires a SECLABEL; none was specified.
X'08' | X'38' | X'0008' | Request failed. SECLABEL checking failed. Indicates the user is not authorized to the SECLABEL.
X'08' | X'38' | X'000C' | Request failed. SECLABEL checking failed. The system was in a multilevel secure status, and the dominance check failed.
X'08' | X'38' | X'0010' | Request failed. SECLABEL checking failed. Neither the user's nor the submitter's SECLABELs dominate. They are disjoint.
X'08' | X'44' | X'0000' | Request failed. A default token is used as input token.
X'08' | X'48' | X'0000' | Request failed. Indicates that an unprivileged user issued a RACROUTE REQUEST=VERIFY in a tranquil state (MLQUIET).
X'08' | X'4C' | X'0000' | Request failed. NODES checking failed. Submitter's node is not allowed access to execution node.
X'08' | X'4C' | X'0004' | Request failed. NODES checking failed. NJE failure: UACC of NONE for USERID type of NODES profile.
X'08' | X'4C' | X'0008' | Request failed. NODES checking failed. NJE failure: UACC of NONE for GROUP type of NODES profile.
X'08' | X'4C' | X'000C' | Request failed. NODES checking failed. NJE failure: UACC of NONE for SECLABEL type of NODES profile.
X'08' | X'4C' | X'0010' | Request failed. NODES checking failed. NJE failure: No local submit node specified.
X'08' | X'4C' | X'0014' | Request failed. NODES checking failed. NJE failure: Reverification of translated values failed.
X'08' | X'50' | X'0004' | Request failed. Indicates that a surrogate submit attempt failed. Indicates the SURROGAT class was inactive.
X'08' | X'50' | X'0008' | Request failed. Indicates that a surrogate submit attempt failed. Indicates the submitter is not permitted by the user's SURROGAT class profile.
X'08' | X'50' | X'000C' | Request failed. Indicates that a surrogate submit attempt failed. Indicates that the submitter is not authorized to the SECLABEL under which the job is to run.
X'08' | X'54' | X'0000' | Request failed. Indicates that a JESJOBS check failed.
X'08' | X'64' | X'0000' | Request failed. Indicates that the CHECK subparameter of the RELEASE keyword was specified on the execute form of the RACROUTE REQUEST=VERIFY macro; however, the list form of the macro does not have the same release parameter. Macro processing terminates.
Parent topic: IBM SAF and RACF Error Codes


Error Codes for AUTH Requests

The return code and reason code values documented in the following table are associated with RACROUTE REQUEST=AUTH requests. AUTH requests are issued to check the authorization of an already verified user to access a protected resource. The most common use of AUTH is to check if a user is authorized to access a specific data set.

SAF Return Code RACF Return Code RACF Reason Code Description
X'00' X'00' X'0000' Request completed successfully.

The user is authorized by RACF to obtain use of a RACF-protected resource.

X'00' X'00' X'0004' Request completed successfully.

The user is authorized by RACF to obtain use of a RACF-protected resource. Indicates one of the following:

  • STATUS=ERASE was specified and the data set is to be erased when scratched
  • the warning status of the resource was requested by the RACROUTE REQUEST=AUTH issuer's setting bit X'10' at offset 12 decimal in the request-specific portion of the RACROUTE REQUEST=AUTH parameter list with the resource in warning mode.
X'00' X'00' X'0010' Request completed successfully.

The user is authorized by RACF to obtain use of a RACF-protected resource. When CLASS=TAPEVOL, indicates the TAPEVOL profile contains a TVTOC.

X'00' X'00' X'0020' Request completed successfully.

The user is authorized by RACF to obtain use of a RACF-protected resource. When CLASS=TAPEVOL, indicates that the TAPEVOL profile can contain a TVTOC, but currently does not (for a scratch pool volume).

X'00' X'00' X'0024' Request completed successfully.

The user is authorized by RACF to obtain use of a RACF-protected resource. When CLASS=TAPEVOL, indicates that the TAPEVOL profile does not contain a TVTOC.

X'00' X'14' X'00XX' Request completed successfully.

Requested function with STATUS=ACCESS specified has completed successfully. The user's highest access to the specified resource is indicated by one of the following reason codes:

  • 00

    The user has no access.

  • 04

    The user has READ authority.

  • 08

    The user has UPDATE authority.

  • 0C

    The user has CONTROL authority.

  • 10

    The user has ALTER authority.

X'04' X'00' X'0000' Request could not be completed.

No RACF decision was possible. No security decision could be made. RACF is not installed -or- the specified requester, subsystem, or class is not in the RACF router table -or- the specified class is not in the RACF class descriptor table.

X'04' X'04' X'0000' Request could not be completed. No RACF decision was possible.

The specified resource is not protected by RACF.

Note: Note:

If PROTECTALL is active, no profile is found, and the user ID whose authority was checked does not have the SPECIAL attribute, RACF returns a return code X'08' instead of a return code X'04' and denies access.

One of the following has occurred:

  • There is no RACF profile protecting the resource
  • RACF is not active
  • Specified class is not active
  • Specified class requires SETROPTS RACLIST option to be active and it is not.
  • CLASS TEMPDSN was active and the dataset is a temporary dataset.
X'04' X'04' X'0004' Request could not be completed.

No RACF decision was possible. The specified resource is not protected by RACF.

Indicates STATUS=ERASE was specified and the data set is to be erased when scratched.

X'08' X'08' X'0000' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

Indicates a normal completion. A possible cause would be PROTECTALL is active, no profile is found, and the user ID whose authority was checked does not have the SPECIAL attribute.

X'08' X'08' X'0004' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

Indicates STATUS=ERASE was specified and the data set is to be erased when scratched.

X'08' X'08' X'0008' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

Indicates DSTYPE=T or CLASS=TAPEVOL was specified and the user is not authorized to use the specified volume.

X'08' X'08' X'000C' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

Indicates the user is not authorized to use the data set.

X'08' X'08' X'0010' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

Indicates DSTYPE=T or CLASS=TAPEVOL was specified and the user is not authorized to specify TAPELBL=(,BLP).

X'08' X'08' X'0014' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

Indicates the user is not authorized to open a non-cataloged data set.

X'08' X'08' X'0018' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

Indicates the user is not authorized to issue RACROUTE REQUEST=AUTH when system is in tranquil state (MLQUIET).

X'08' X'08' X'001C' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

A user with EXECUTE authority to the data set profile specified ATTR=READ, and RACF failed the access attempt.

X'08' X'08' X'0020' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

The user's security label does not dominate that of the resource; it fails SECLABEL authorization checking.

X'08' X'08' X'0024' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

The user's security label can never dominate that of the resource.

X'08' X'08' X'0028' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

The resource must have a security label, but does not have one.

X'08' X'0C' X'0000' Request failed.

The OLDVOL specified was not part of the multivolume data set defined by VOLSER, or it was not part of the same tape volume defined by ENTITY.

X'08' X'10' X'00XX' Request failed.

RACROUTE REQUEST=VERIFY was issued by a third party, and RACROUTE REQUEST=AUTH failed. The reason code 00XX value is the RACF return code from the RACROUTE REQUEST=VERIFY.

X'08' X'64' X'0000' Request failed.

Indicates that the CHECK subparameter of the RELEASE keyword was specified on the execute form of the RACROUTE REQUEST=AUTH macro; however, the list form of the macro does not have the same RELEASE parameter. Macro processing terminates.

Parent topic: IBM SAF and RACF Error Codes


Mainframe Access Audit Report Program

Mainframe Access' optional audit log feature records client logon and logoff information to a VSAM data set. For a description of how to allocate the audit log data set and enable the recording see the section Allocating and Initializing an Audit Log Data Set in the chapter Configuration. Mainframe Access also provides a batch reporting program to list the audit log records. This section describes the use of the audit log report program.

  • Running the Audit Report Program
  • Audit Report Abend Codes
  • Audit Report Diagnostic Messages
Parent topic: Troubleshooting
Related information
Allocating and Initializing an Audit Log Data Set


Running the Audit Report Program

Member AUDRPT in the Mainframe Access <hlq>.CNTL data set is a sample job for running the audit report program. Customize this job with a valid JOB card and the correct data set qualifier for your installation. The sample member is shown below.

//MFASETUP JOB (MFA),'RUN AUDIT REPORT',CLASS=A,MSGCLASS=A
//*
//AUDITRPT PROC DSNQUAL='HLQ'
//*
//*------------------------------------------------------------------*
//*                                                                  *
//* Micro Focus Mainframe Access - Run the Audit Log Report          *
//*                                                                  *
//* Change the DSNQUAL value on the PROC statement to the correct    *
//* value for your installation.                                     *
//*------------------------------------------------------------------*
//*
//*------------------------------------------------------------------*
//* Step 1: Run the audit report utility to list the records in the  *
//*         audit log dataset.                                       *
//*------------------------------------------------------------------*
//*
//AUDITRPT EXEC PGM=AUDITRPT,REGION=0M
//STEPLIB  DD   DSN=&.DSNQUAL..LOADLIB,DISP=SHR
//AUDITIN  DD   DSN=&.DSNQUAL..AUDIT,DISP=SHR
//SYSPRINT DD   SYSOUT=*
//SYSTERM  DD   SYSOUT=*
//SYSUDUMP DD   SYSOUT=*
//         PEND
//AUDITRPT EXEC AUDITRPT

When you have customized the job, submit it for execution. A report similar to the following is written to a SYSOUT data set.

                                                            Audit Log Report

  Report date and time: FRI JUL 25 16:37:57 2003

  Audit data set: <hlq>.AUDIT

  Type     Record    Sess  User      IP Address       Partner    Date+Time                Type of
  of       Sequence  ID    ID                         LU                                  Encryption used (see note)
  Record

  Logoff        1    00000 CSIRLW2   10.24.11.15      MFADIR     FRI JUL 25 16:02:51 2003
  Logoff        3    00000 CSIRLW1   10.24.11.15      MFADIR     FRI JUL 25 16:03:33 2003
  Logoff        5    00000                                       FRI JUL 25 16:04:22 2003 N
  Logoff       10    00000                                       FRI JUL 25 16:35:48 2003 N
  Logon         0    00001 CSIRLW2   10.24.11.15      MFADIR     FRI JUL 25 16:02:27 2003
  Logon         2    00002 CSIRLW1   10.24.11.15      MFADIR     FRI JUL 25 16:03:20 2003
  Logon         4    00003 CSIRLW1   10.24.11.15      LUDB27R    FRI JUL 25 16:03:59 2003 P
  Logon         6    00004           10.24.11.15      CICSTSR7   FRI JUL 25 16:34:32 2003 N
  Logon         7    00005           10.24.11.15      CICSTSR6   FRI JUL 25 16:34:33 2003 N
  Logon         8    00006           10.24.11.15      CICSTSR3   FRI JUL 25 16:34:34 2003 N
  Logon         9    00007 CSIRLW1   10.24.11.15      IMS6PPC    FRI JUL 25 16:35:42 2003 N

  Note: Encryption values   N = None, P = Password, X = Packet encryption, C = Compression is in use

  Total type 0 records =         11
  Total logon records  =          7
  Total logoff records =          4
Parent topic: Mainframe Access Audit Report Program


Audit Report Abend Codes

The following table lists the user abends that may be issued by the audit report program.

User Abend Code | Description of Cause | Recommended Action
1211 | This abend is issued when a GETMAIN request fails. A console message is also issued to indicate the failure condition. A program dump is not requested. | Increase the region size for the audit report program. If the problem persists contact our Product Support.
Parent topic: Mainframe Access Audit Report Program


Audit Report Diagnostic Messages

The following messages may be issued by the audit report program when error conditions occur.

AUD0001E: DDNAME xxxxxxxx WAS NOT FOUND

This message appears when either the SYSPRINT or AUDITIN DD statements are missing. Add the missing DD statements to the JCL for the job.

AUD0002E: OPEN FAILED FOR xxxxxxxx FILE

This message appears when either SYSPRINT or AUDITIN fails to open. Examine associated system error messages to determine the reason for the failure.

AUD0003E: VSAM ACB FAILED FOR xxxxxxxx
AUD0003E: RETURN CODE IS xxxxxxxx
AUD0003E: REASON CODE IS xxxxxxxx

These messages appear when a critical error occurs while accessing the AUDITIN VSAM data set. The program terminates with the return code 16. Examine any associated system error messages and the VSAM return code and reason code values to determine the reason for the failure.

Parent topic: Mainframe Access Audit Report Program


Obtaining a VTAM Buffer Trace

During the process of resolving a problem, our Product Support may require you to obtain and submit a VTAM buffer trace (and possibly other VTAM trace data). This section describes how to use IBM's Generalized Trace Facility (GTF) to capture the relevant data.

The procedure for gathering the trace is as follows:

  1. Make sure that Mainframe Access, the clients and the target servers are all ready and at a point where you want to start tracing. For example, if the problem is associated with a specific CICS distributed transaction, bring the client up to the point where the transaction will be issued.
  2. Start GTF (see the section Starting GTF)
  3. Activate the VTAM trace (see the section Activating the VTAM Trace)
  4. Perform the activity that you want to trace (for example, run the transaction that fails)
  5. Deactivate the VTAM trace (see the section Deactivating the VTAM Trace)
  6. Stop GTF (see the section Stopping GTF)
  7. Package the raw GTF trace data set for transmission to our Product Support.
  8. Use the File Transfer Protocol (FTP) utility to send the packaged trace to Micro Focus. Use binary mode for the transfer.
  • Starting GTF
  • Activating the VTAM Trace
  • Deactivating the VTAM Trace
  • Stopping GTF
  • Formatting VTAM GTF Trace Records
  • Obtaining an SVC Dump of Mainframe Access
  • Packaging and Transmitting Diagnostic Data
Parent topic: Troubleshooting
Related information
Starting GTF
Activating the VTAM Trace
Deactivating the VTAM Trace
Stopping GTF


Starting GTF

Mainframe Access provides a sample procedure, MFAGTF, for running GTF; its use is described in the section Adding the GTF Procedure to a System Procedure Library in the chapter Configuration. You may want to pre-allocate a permanent GTF trace data set on DASD that can be reused each time you start MFAGTF. If you do so, update the MFAGTF procedure to use this data set.

A PDS member is normally used to automate the specification of GTF options when GTF is started and the sample procedure uses parameters from another sample member, GTFCNTL. This sample is set up to start GTF for recording Mainframe Access' activity trace (USR '0E9' records) and VTAM's buffer trace (USR 'FEF' and 'FF1' records).

A sample system log for the startup of GTF is shown below. Remember to have Mainframe Access and other software components that are part of the tracing activity already running, connected and ready to go, if possible.

  S MFAGTF.MYGTF
  $HASP100 MFAGTF   ON STCINRDR
  IEF695I START MFAGTF WITH JOBNAME MFAGTF IS ASSIGNED TO USER RWITEK, GROUP CSIDVLP
  $HASP373 MFAGTF   STARTED
  IEF403I MFAGTF - STARTED - TIME=16.34.12
  AHL121I  TRACE OPTION INPUT INDICATED FROM MEMBER GTFCNTL  OF PDS
  <hlq>.CNTL
  TRACE=USRP
  USR=(FF1,FEF,0E9)
  END
  AHL103I  TRACE OPTIONS SELECTED --USR=(FEF,FF1,0E9)
  AHL906I THE OUTPUT BLOCK SIZE OF    27998 WILL BE USED FOR OUTPUT 997
          DATA SETS:
            <hlq>.TRACE
  AHL080I GTF STORAGE USED FOR GTF DATA: 998
          GTFBLOCK STORAGE       82K BYTES (BLOK=        40K)
          PRIVATE STORAGE      1038K BYTES
          SADMP HISTORY          54K BYTES (SADMP=       40K)
          SDUMP HISTORY          54K BYTES (SDUMP=       40K)
          ABEND DUMP DATA         0K BYTES (ABDUMP=       0K)
  AHL031I GTF INITIALIZATION COMPLETE

GTF is now up and running and ready to record type 'FEF' and 'FF1' records from VTAM. z/OS may also force some USR records into the trace data set for system components. GTF wraps trace data when writing trace records to a DASD data set. This means that you can leave GTF tracing on for a long time to catch an intermittent problem, then stop the trace soon after the problem occurs. However, if you do not stop the trace soon after the problem occurs, the trace data that you collected may be overwritten by trace data from other system components.

Parent topic: Obtaining a VTAM Buffer Trace
Related information
Adding the GTF Procedure to a System Procedure Library


Activating the VTAM Trace

When you are ready to perform an action that you want to trace, activate the VTAM buffer trace for the Mainframe Access ACB. You do this using a z/OS Modify command to VTAM. In this example the VTAM JCL procedure name is VTAM. The name may be different on your z/OS system. The only other thing you may want to change is the ID= parameter so that it specifies the name of your Mainframe Access VTAM ACB.

  F VTAM,TRACE,TYPE=BUF,ID=MFM62ACB,AMOUNT=FULL
  IST097I MODIFY ACCEPTED
  IST1515I BUFFER TRACE ACTIVE
  IST1144I TRACE INITIATED FOR DDINET1.MFM62ACB 316
  IST1045I NODE TYPE = APPL
  IST314I END

GTF should now be up and running and VTAM should be creating TYPE=BUF trace records for any activity associated with MFM62ACB. If someone has previously started a TYPE=BUF trace for another VTAM resource and did not bother to stop the trace, these records may also appear in the trace data set and complicate the analysis of what you are tracing.

Parent topic: Obtaining a VTAM Buffer Trace


Deactivating the VTAM Trace

When you have finished performing the activity to be traced, turn off the VTAM TYPE=BUF trace for the Mainframe Access ACB. Use the z/OS Modify command as follows:

  F VTAM,NOTRACE,TYPE=BUF,ID=MFM62ACB
  IST097I MODIFY ACCEPTED
  IST1143I TRACE TERMINATED FOR DDINET1.MFM62ACB 349
  IST1045I NODE TYPE = APPL
  IST314I END
Parent topic: Obtaining a VTAM Buffer Trace


Stopping GTF

Stop the GTF process using the z/OS Stop (P) command. In this example GTF was started using "S MFAGTF.MYGTF" where the .MYGTF is assigned as an identifier for the GTF process that is then specified in the Stop command.

  P MYGTF
  AHL006I GTF ACKNOWLEDGES STOP COMMAND
  AHL904I THE FOLLOWING TRACE DATASETS CONTAIN TRACE DATA : 353
            <hlq>.TRACE
  IEF404I MFAGTF - ENDED - TIME=11.48.15
  $HASP395 MFAGTF   ENDED
  $HASP250 MFAGTF PURGED -- (JOB KEY WAS B5A444E4)

The trace data set, <hlq>.TRACE in this example, now has the raw GTF data.

Parent topic: Obtaining a VTAM Buffer Trace


Formatting VTAM GTF Trace Records

There may be times when you need, or want, to examine the GTF trace data. In this case, the raw data collected by GTF needs to be processed by a formatting program such as IBM's Interactive Problem Control System (IPCS). You can run IPCS either using a TSO command under ISPF or as a batch job. To run IPCS you need an IPCS dump directory VSAM data set. If you do not already have a dump directory, you can allocate one using a job similar to the following.

//jobname JOB (accounting),'name',CLASS=?,MSGCLASS=?,NOTIFY=userid
//--------------------------------------------------------------------
//* Allocate an IPCS dump directory VSAM data set
//--------------------------------------------------------------------
//IDCAMS   EXEC PGM=IDCAMS
//SYSPRINT DD   SYSOUT=*
 DELETE <hlq>.DIR
 DEFINE CLUSTER (NAME(<hlq>.DIR)                -
                SHAREOPTIONS(1)                 -
                RECSZ(256 3072)                 -
                KEYS(128 0)                     -
                VOLUMES(volser)
          INDEX (NAME(<hlq>.DIRINDEX)           -
                TRK(15 5))                      -
          DATA  (NAME(<hlq>.DIRDATA)            -
                CYLINDERS(5 1)                  -
                CISZ(X'1000'))

This example JCL runs IPCS to print all 'FEF' and 'FF1' records from the GTF trace data set.

//jobname JOB (accounting),'name',CLASS=?,MSGCLASS=?,NOTIFY=userid
//--------------------------------------------------------------------
//* Run IPCS batch to print GTF trace records
//--------------------------------------------------------------------
//IPCSBAT  EXEC PGM=IKJEFT01,DYNAMNBR=20,REGION=0M
//IPCSDDIR DD DSN=<hlq>.DIR,DISP=SHR
//IPCSPRNT DD SYSOUT=*
//TRACE    DD DSN=<hlq>.TRACE,DISP=SHR
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
 IPCS NOPARM
 DROPDUMP DDNAME(TRACE)
 SETDEF DDNAME(TRACE) NOCONFIRM
 GTFTRACE DDNAME(TRACE),USR(FEF,FF1),TERMINAL,NOPRINT
 END
Parent topic: Obtaining a VTAM Buffer Trace


Obtaining an SVC Dump of Mainframe Access

During the process of resolving a problem, our Product Support may require you to obtain and submit a dump of the Mainframe Access address space. This section describes how to use IBM's DUMP command to create the dump data set. Using the following procedure, you can obtain a dump without stopping or canceling the Mainframe Access address space.

The procedure for creating the dump is as follows:

  1. Issue the DUMP command
  2. Respond to the DUMP command options request
  3. Package the dump data set for transmission to our Product Support
  4. Use the File Transfer Protocol (FTP) utility to send the packaged dump to Micro Focus. Use binary mode for the transfer.

The following example shows a DUMP command and the response to the request for operands in bold face. You use the COMM parameter of the DUMP command to specify a meaningful title for the dump. The operands specified in the sample reply, SDATA=(RGN,LSQA,PSA,SUM,SWA,TRT,CSA,LPA), are normally needed for any Mainframe Access dump; you should specify them as shown. Technical support may request additional, or different, options for a specific problem. After the options have been entered it will take the system anywhere from a few seconds to a few minutes to complete the dump. The IEA611I COMPLETE DUMP message indicates successful completion of the command and it identifies the dump data set that needs to be saved and packaged up for transmission. In this example, the system has created data set SYS1.CSIA.DMP00032 to contain the dump data.

  DUMP COMM=(MFA DUMP JULY 28 2003)
  *63 IEE094D SPECIFY OPERAND(S) FOR DUMP COMMAND
  R 63,JOBNAME=MFA,SDATA=(RGN,LSQA,PSA,SUM,SWA,TRT,CSA,LPA)
   IEE600I REPLY TO 63 IS;JOBNAME=MFA,SDATA=(RGN,LSQA,PSA,SUM,SWA,TRT
   IEA794I SVC DUMP HAS CAPTURED: 138
   DUMPID=032 REQUESTED BY JOB (*MASTER*)
   DUMP TITLE=MFA DUMP JULY 28 2003
   IEF196I IGD100I 0309 ALLOCATED TO DDNAME SYS00036 DATACLAS (        )
   IEF196I IEF285I   SYS1.CSIA.DMP00032                           CATALOGED
   IEF196I IEF285I   VOL SER NOS= DUMP01.
   IEA611I COMPLETE DUMP ON SYS1.CSIA.DMP00032 142
   DUMPID=032 REQUESTED BY JOB (*MASTER*)
   FOR ASID (00A5)
   INCIDENT TOKEN: ROCKPLEX CSIA     07/28/2003 21:56:11
Parent topic: Obtaining a VTAM Buffer Trace


Packaging and Transmitting Diagnostic Data

This section provides suggestions and guidelines that will help if you need to send diagnostic data to our Product Support. When you need to send relatively small amounts of text data (for example, short Mainframe Access activity traces, parameter settings, excerpts from the system log, excerpts from a dump listing, etc.), it is often convenient to simply include the text in an email or as a text file attachment to an email. Large amounts of data and non-textual information should be packaged and transmitted as described in the following paragraphs.

After gathering large amounts of diagnostic data (for example, SVC dumps, GTF traces, Mainframe Access activity traces, system log contents, etc.), the most expedient way to send the information is using the TCP/IP File Transfer Protocol (FTP) utility. Before you send the data, it is good practice to package the data for transmission. This will reduce transmission time by compressing the data and it will facilitate the handling of data when it is received.

Our Product Support can accommodate data that is packaged using the TSO Interactive Data Transmission Facility (the TSO XMIT and RECEIVE commands) or data that is packaged using IBM's TRSMAIN program (the terse utility). Mainframe Access sample TSOXMIT provides a job that demonstrates the use of TSO XMIT to package a data set for transmission. If you want to use TRSMAIN, we recommend that you start by asking the z/OS systems programming staff at your company if TRSMAIN is already installed and available for use. If it is not, you can download the IBM TRSMAIN program from the ftp.software.ibm.com Web site using FTP. You can access the download using the anonymous user ID with your email address provided as the password. Use change directory commands to locate the TRSMAIN downloads in /s390/mvs/tools/packlib at this IBM ftp site. You should find a single binary file and both plain text and HTML explanations of the procedure for installing the utility.

When your data is ready for transmission, our Product Support can provide additional instructions for sending your data to the ftp.microfocus.com site. This may include specific directory locations, filenames, etc. that should be used. After you have transferred the data, please send a follow-up email to your support representative. This note should list the files that you have sent, the packaging tool(s) that you have used, and the z/OS data set characteristics of both the packaged files and the data sets that will be created when the packages are opened. The z/OS data set characteristics should include the RECFM, LRECL, BLKSIZE, primary space allocation and secondary space allocation.

Parent topic: Obtaining a VTAM Buffer Trace


Customizing Data Connect

This section describes advanced configuration for the Mainframe Access Data Connect server.

  • Introduction
  • Samples for Configuration
  • JCL Change for Data Connect
  • Customizing the FSTAB Mapping Table and - 2
Parent topic: Configuring and Administering the Mainframe


Introduction

At the completion of Mainframe Access installation and quick configuration, the Mainframe Access Data Connect server is ready to use for most Data Connect applications. This chapter will help you with the necessary customization if you need to change the default user verification and data set authorization checking. This chapter also describes how to customize a FSTAB file mapping table and the MFAVCTL file mapping data set.

Parent topic: Customizing Data Connect


Samples for Configuration

The installation procedure places several samples in the <hlq>.MFACNTL data set. If a sample is provided for a configuration task, use it as a starting point for your configuration. Usually you need to edit the sample, replacing provided information with information that is unique to your system.

The following table summarizes the samples that are provided for Mainframe Access Data Connect server.

MEMBER | DESCRIPTION
FSTAB | Assembler language macro used by the MFASFTAB sample.
MFASFTAB | Sample job and source statements for creating your own FSTAB module for file name mapping operations.
Parent topic: Customizing Data Connect


JCL Change for Data Connect

In order to supply all MFA and Data Connect function within one authorized library, the Data Connect module names have been renamed, and slightly reorganized as static load modules rather than dynamic overlays. All Data Connect load modules now begin with the prefix MFD.

//*--------------------------------------------------------------*
       //* Micro Focus Mainframe Access - Data Connect V4.00
       //*--------------------------------------------------------------*
       //MFAS EXEC PGM=MFDSTART,PARM='APPLID=MFA62ACB',
       //   REGION=0M,TIME=1440
       //STEPLIB  DD DISP=SHR,DSN=MFA40.PROD.LOADLIB
       //SYSUDUMP DD SYSOUT=*
       //FSMSGA   DD SYSOUT=*         for IDCAMS
       //FSMSGC   DD SYSOUT=*         for APPC errors
       //FSMSGL   DD SYSOUT=*         for FileShare log
       //VSAMCTL  DD DISP=SHR,DSN=MFA40.PROD.MFAVCTL
Parent topic: Customizing Data Connect


Customizing the FSTAB Mapping Table and - 2

If you wish to define the Data Connect datasets and alternate indexes to be allocated, then you need to create the DDNAME/DSNAME cross reference table, FSTAB. The MFASFTAB member in the MFACNTL data set contains a job that you can user to create the FSTAB. The cross reference table converts filenames used in SELECT clauses in your COBOL application program to MVS dataset names or ddnames. In the COBOL program, you can assign a filename directly to an MVS ddname, an MVS dataset name or an entry requiring conversion by this table. If an entry is not found in the cross reference table, an assumption is made that the COBOL SELECT clause contains an MVS dataset name and dynamic allocation is attempted.

All entries in the table are optional. The table allows the following formats:

For short term dynamic allocation - dataset is freed at close:

FSTAB  'PC-NAME',DSN=MVS-DATASET-NAME
       [,MEM=MEMBNAME]   optional for PDS member name

For long term dynamic allocation - dataset freed at termination:

FSTAB  'PC-NAME',DSN=MVS-DATASET-NAME,DDN=DDNAME
       [,MEM=MEMBNAME]   optional for PDS member name

For long term allocation - //DDNAME in start-up JCL:

FSTAB  'PC-NAME',DDN=DDNAME

VSAM allocation adding alternate indexes:

FSTAB  'PC-NAME',DSN=MVS-DATASET-NAME,                 X
       AIX=(VSAM-AIX1,VSAM-AIX2,VSAM-AIX3)
Note:

COBOL application programs must define alternate indexes in the same order as they are defined in the table.

An exception to this rule is if the name is 1-8 characters without a period. In this case the name represents a member name in the dynamic allocation control file for new datasets (MFAVCTL). This enhancement to the MFA Data Connect Server is provided to remove the FSTAB requirement when using VSAM alternate indexes. This enhancement uses members in the MFAVCTL library to create dynamic FSTAB entries for VSAM files which have alternate indexes. Each member in the MFAVCTL library defines a VSAM file and its indexes. Only one VSAM file can be specified in each member. The control records within a member are 80 bytes long and begin with a keyword followed by its value. All member names for this facility must begin with a '$' or whatever keyboard character maps to a X'5C'. The keywords are VSAM= and AIXn=, when n is a value from 1 to 9. Following VSAM= is the MVS VSAM dataset name. This record must be the first record in the member. The keywords AIX1 through AIX9 identify the alternate index PATH files. They must be specified in the same order as in the COBOL program.

For example, in the COBOL program:

FILE-CONTROL.
 SELECT CLAIM-FILE ASSIGN TO PATCLMX
        ORGANIZATION IS INDEXED
        ACCESS IS RANDOM
        RECORD KEY IS PATIENT-CLIAM-NUMBER
        ALTERNATE RECORD KEY IS MEDICARE DUPLICATES
        ALTERNATE RECORD KEY IS MEDICAID-KEY DUPLICATES
        ALTERNATE RECORD KEY IS PRIVATE-INS-KEY DUPLICATES
        ALTERNATE RECORD KEY IS PATIENT-NAME
        ALTERNATE RECORD KEY IS CONTROL-NUMBER
        ALTERNATE RECORD KEY IS PAYMENT-ID
        STATUS IS VSAM-FILE-STATUS.

As an FSTAB entry:

FSTAB 'PATCLMX',
           DSN=CSI01V.PATCLM.PATIENT.BILLING,
           AIX=(CSI01V.PATCLM.BY.MEDICARE.PATH,
           CSI01V.PATCLM.BY.MEDICAID.PATH,
           CSI01V.PATCLM.BY.INS.POLICY.PATH,
           CSI01V.PATCLM.BY.NAME.PATH,
           CSI01V.PATCLM.BY.CONTROL.PATH,
           CSI01V.PATCLM.BY.PAYMENT.PATH)

As a MFAVCTL library member:

VSAM=CSI01V.PATCLM.PATIENT.BILLING
AIX1=CSI01V.PATCLM.BY.MEDICARE.PATH
AIX2=CSI01V.PATCLM.BY.MEDICAID.PATH
AIX3=CSI01V.PATCLM.BY.INS.POLICY.PATH
AIX4=CSI01V.PATCLM.BY.NAME.PATH
AIX5=CSI01V.PATCLM.BY.CONTROL.PATH
AIX6=CSI01V.PATCLM.BY.PAYMENT.PATH

Assume that the name of the MFAVCTL member for the above control statements is $PATCLM6, then the MFEXTMAP.DAT entry would be: PATCLMX $PATCLM6. The above FSTAB and MFAVCTL member are functionally equivalent.

Parent topic: Customizing Data Connect


Configuring Access to External Library Management Systems

This section describes the Mainframe Access support for external library management systems and change management systems.

  • About External Library Management
  • Panvalet
  • Librarian
  • Endevor
  • ChangeMan ZMF
Parent topic: Configuring and Administering the Mainframe


About External Library Management

Mainframe Access provides seamless access to objects housed in repositories controlled by the following external management systems:

  • Panvalet from Computer Associates (www.cai.com)
  • Librarian from Computer Associates (www.cai.com)
  • Endevor from Computer Associates (www.cai.com)
  • ChangeMan ZMF from Serena Software, Inc. (www.serena.com)

Contact the appropriate vendor for further information about these products.

Parent topic: Configuring Access to External Library Management Systems
Related information
www.cai.com
www.serena.com


Panvalet

Panvalet is a direct access library system marketed by Computer Associates. It's primary use is as a source control system for software development.

  • About Panvalet
  • References
  • Panvalet Suffix Table
  • Suffix Table Override
  • Panvalet Security Exit
Parent topic: Configuring Access to External Library Management Systems


About Panvalet

With Panvalet, all source members are managed as fixed length records. The default size is the historical card image of 80 bytes. Panvalet may be used to manage any fixed-length data up to 4096 characters in length.

Panvalet provides licensed users with programmable access to their repository services via the PAM API. This is a read-only interface which permits multiple concurrent access for Mainframe Access threads to browse source members residing in Panvalet repositories. During Server initialization, Mainframe Access will attempt to load this interface into memory. If this API interface is available through the standard search order (STEPLIB, JOBLIB, or SYS1.LINKLIB at the customer site) then Panvalet services will be offered. Startup initialization messages will indicate if Panvalet is available.

It is a customer responsibility to provide a suitable STEPLIB concatenation which will allow selection of the desired release and version of the Panvalet components. At most sites, PANVALET is installed as an MVS Subsystem. Therefore the API will already be available within SYS1.LINKLIB. No override would be necessary unless a new version is being tested.

     //STEPLIB DD DSN=your.MFA30.LOADLIB,DISP=SHR
     //        DD DSN=CAI.PANV144.CAILIB,DISP=SHR

The following messages are typical of the information written to the SYSLOG during Mainframe Access startup:

       MFM0063I: MFA Direct is active
       MFM0064I: MFA Direct number of processing tasks is 5
       MFMDS051I CA/LIBrarian Ready
       MFMDS052I CA/PanValet Ready
       MFMDS053I CA/ENDEVOR API 39 Ready
       MFMDS055I MCG/RPC feature active
       MFMDS001I DSS Server Ready
       MFM0001I: Mainframe Access V3.01 (bt2) is active

For source additions or updates under Panvalet, Mainframe Access must invoke the standard Panvalet batch utility PAN#1. Access to this utility will be serialized, since Panvalet does not support multiple, concurrent access to this service. In some cases, a customer may have renamed the Batch Update utility PAN#1. If this is the case, the new name at this site must be defined to Mainframe Access as a parameter override.

Parent topic: Panvalet


References

  • PANVALET System Management Guide
  • PANVALET Messages Guide
  • PANVALET Installation Guide
  • PANVALET User Guide
  • PANVALET Extended Features Guide
Parent topic: Panvalet


Panvalet Suffix Table

Panvalet recognizes the following programming language or object types:

  • BAL
  • COBOL
  • DATA
  • FORTRAN
  • JCL
  • PL/I
  • RPG

Specification of such a native language type allows Panvalet to format the source files, and automatically add or remove the sequence numbers in the appropriate position for that language. In order to automate this language selection process, Mainframe Access has introduced a Panvalet Suffix Table to specify the language type based upon the file suffix as used on the workstation. In addition, the Suffix Table also specifies the default options to be specified on the ADD command of the PAN#1 batch update utility.

SUFFIX | ++ADD Options
(default) | DATA,LIST,NOFORMAT
ASM | BAL,LIST,NOFORMAT
ASSEM | BAL,LIST,NOFORMAT
BAL | BAL,LIST,NOFORMAT
BMS | BAL,LIST,NOFORMAT
CBL | COBOL,LIST,NOFORMAT
CNTL | JCL,LIST,NOFORMAT
COB | COBOL,LIST,NOFORMAT
COBOL | COBOL,LIST,NOFORMAT
COP | COBOL,LIST,NOFORMAT
COPY | COBOL,LIST,NOFORMAT
CPY | COBOL,LIST,NOFORMAT
DATA | DATA,LIST,NOFORMAT
DBD | BAL,LIST,NOFORMAT
JCL | JCL,LIST,NOFORMAT
JOB | JCL,LIST,NOFORMAT
MAC | BAL,LIST,NOFORMAT
MFS | BAL,LIST,NOFORMAT
PLI | PL/1,LIST,NOFORMAT
PL1 | PL/1,LIST,NOFORMAT
PSB | BAL,LIST,NOFORMAT

The above table describes the default Suffix Table as provided within Mainframe Access. If no changes are desired, no further customization is necessary.

Parent topic: Panvalet


Suffix Table Override

The built-in Panvalet Suffix Table may be replaced by including a special DD card in the Mainframe Access task JCL as follows:

     //PANSUFX  DD  DSN=your.MFA30.CNTL(PANVALET),DISP=SHR

During initialization, this text file will be analyzed and a new Suffix Table will be created dynamically. The first entry defines a default language type to be used if no match is found in the table. The following extract illustrates the free-form format of the text file:

      *
      * MFA PANVALET CONFIGURATION CONVERSION TOOL
      *      AS ON 06/07/2003 AT 12:40
      *
      * SUFFIX TYPE     ++ADD OPTIONS
      ******** ******** ***********************
      *
      DEFAULT  DATA     LIST,NOFORMAT
      ASM      BAL      LIST,NOFORMAT
      ASSEM    BAL      LIST,NOFORMAT
      BAL      BAL      LIST,NOFORMAT
      BMS      BAL      LIST,NOFORMAT
      DBD      BAL      LIST,NOFORMAT
      MAC      BAL      LIST,NOFORMAT
      MFS      BAL      LIST,NOFORMAT
      MLC      BAL      LIST,NOFORMAT
      PSB      BAL      LIST,NOFORMAT
      CBL      COBOL    LIST,NOFORMAT
      COB      COBOL    LIST,NOFORMAT
      COBOL    COBOL    LIST,NOFORMAT
      COP      COBOL    LIST,NOFORMAT
      COPY     COBOL    LIST,NOFORMAT
      CPY      COBOL    LIST,NOFORMAT
      JCL      JCL      LIST,NOFORMAT
      JOB      JCL      LIST,NOFORMAT
      PLI      PL/I     LIST,NOFORMAT
      PL1      PL/I     LIST,NOFORMAT

In this way, customers may change the search order, the suffix name, and the Panvalet ADD options to meet their needs. Some customers may have already compiled a custom Suffix Table from Mainframe Access Version 2. A migration tool is provided to convert this configuration back into a text file which may be presented to Mainframe Access Version 3.

 //jobname  JOB (MFA),'PANVALET SUFFIX',CLASS=A,MSGCLASS=X
 //***************************************************************
 //*        EXTRACT PANVALET SUFFIX FROM MFA SERVER V2
 //***************************************************************
 //*
 //PVSUFFX  EXEC PGM=MFAUTL01,REGION=1M
 //STEPLIB   DD  DISP=SHR,DSN=your.MFA.V3.LOADLIB
 //MFALIB    DD  DISP=SHR,DSN=your.MFA.V2.LOADLIB
 //MFAPARM   DD  DISP=SHR,DSN=your.parms.CNTL(PANVALET)
 //
Parent topic: Panvalet


Panvalet Security Exit

MFA supports a customized user exit (MFAPVXIT) that enables you to implement member-level security within your Panvalet repositories. This user exit is required because security is not available via RACF, and a proprietary Panvalet exit (PSPILXIT) is only available under TSO dialogs.

MFAPVXIT is automatically invoked to approve access rights for all Panvalet activity: import, export, and directory requests. A sample exit and test harness is provided within the .CNTL file shipped with the MFA product libraries:

Member | Description
MFAPVXIT | Sample Panvalet member security exit
PVTESTX | Test harness for MFAPVXIT
ASMPVT | Assemble and link PVTESTX
ASMPVX | Assemble and link MFAPVXIT

MFA provides the user ID, member name, and Panvalet master file name to MFAPVXIT, and interprets a return code of zero to mean that access is permitted. Any other return code results in access being denied. This means that the MFAPVXIT can create a directory filter based on the access rights of the individual or his department. The algorithm is entirely up to the site, and will be based on table-driven data compiled into the exit. The sample exit demonstrates how naming conventions, or tables of authorized users can be used to accomplish this.

Parent topic: Panvalet


Librarian

Librarian is a powerful change management system for source modules and data records.

  • About Librarian
  • References
  • Librarian Exit Table
Parent topic: Configuring Access to External Library Management Systems


About Librarian

Under Librarian, all source is stored within proprietary Librarian master files in a highly compressed format. Individual source modules may be stored and retrieved by name. Multiple master files may be defined and shared among the user groups.

Librarian provides licensed users with programmable access to source modules via the File Access Interface Routines (FAIR) API. This is a read-only interface which permits multiple concurrent access for Mainframe Access threads to browse source members residing in a Librarian master file. During Server initialization, Mainframe Access will attempt to load this interface into memory. If this API interface is available through the standard search order (STEPLIB, JOBLIB, or SYS1.LINKLIB at the customer site) then Librarian services will be offered. Startup initialization messages will indicate if Librarian is available. It is a customer responsibility to provide a suitable STEPLIB concatenation which will allow selection of the desired release and version of the Librarian components.

        //STEPLIB DD DSN=your.MFA30.LOADLIB,DISP=SHR
        //        DD DSN=CAI.LIBR43.CAILIB,DISP=SHR

For source additions or updates under Librarian, Mainframe Access will invoke the standard Librarian batch utility AFOLIBR. Access to this utility will be serialized, since Librarian does not support multiple, concurrent access to this service from the same address space. In some cases, a customer may have renamed the Batch Update utility AFOLIBR. If this is the case, the new name at this site must be defined to Mainframe Access as a parameter override.

        MFA_LIBRARIAN_HISTORY=YES           - MFA default
        MFA_LIBRARIAN_UPD_MODULE=LIBRUPD    - site override
Parent topic: Librarian


References

  • Librarian Command Reference Guide
  • Librarian File Access Interface Routines
  • Librarian Messages Guide
  • Librarian Installation Guide
  • Librarian User Guide
  • Librarian Systems Services Guide
  • Librarian Security Administration Guide
Parent topic: Librarian


Librarian Exit Table

Librarian does support user exits under its Batch Update facility. The user exit may be common, or may be assigned to a specific master file. In order to configure this option, MFA references a reserved DD named LIBXIT$. If specified in the JCL, MFA builds a memory table to specify the Output Exit to be used for the given master file.

*  Librarian Exit Table (fixed format)
*
*  EXIT columns 1-8 is an exit module name
*       found in the STEPLIB, JOBLIB, LINKLIB concatenation
*  LIBRARIAN MASTER name resides in columns 11-54
*       any master file with this prefix will invoke the exit
*
* EXIT    Librarian Master file prefix or full name
********  ********************************************
LIBREXIT  PROD.LIB
LBXIT02   MY.LIBRARIAN.MASTER
Parent topic: Librarian


Endevor

Endevor is a full function change control system with signout controls and extensive user customization.

  • About Endevor
  • References
  • Endevor Dependent Regions
  • Endevor C1DEFLTS File
  • Endevor Setup Errors
Parent topic: Configuring Access to External Library Management Systems


About Endevor

Through the use of Exits and Processor Groups, it is possible to automatically re-compile the changed objects, and re-link any components which require those objects. Endevor also has several optional system features such as External Security, and alternate RACF user ID support.

Starting with Release 39, Endevor provides licensed users a powerful Endevor Services API (ENA$NDVR). This interface permits full-function access to read or update source objects residing in an Endevor repository. During Server initialization, Mainframe Access will attempt to load this interface into memory. If this API interface is available through the standard search order (STEPLIB, JOBLIB, or SYS1.LINKLIB at the customer site) then Endevor services will be offered. Startup messages will indicate if Endevor is available. It is a customer responsibility to provide a suitable STEPLIB concatenation for selection of the desired release and version of the Endevor components. Mainframe Access will examine the Endevor C1DEFLTS table to determine the version of Endevor being used. This is necessary because the control structures used by the Endevor API versions are not fully downward-compatible. Mainframe Access must build the API request using the format demanded by the version in effect at your site. If no C1DEFLTS table is found, Endevor support will not be enabled.

        //STEPLIB DD DSN=your.MFA400.LOADLIB,DISP=SHR
        //        DD DSN=CAI.NDVRR16.CSIQAUTU,DISP=SHR
        //        DD DSN=CAI.NDVRR16.CSIQAUTH,DISP=SHR
        //CONLIB  DD DSN=CAI.NDVRR16.CSIQLOAD,DISP=SHR

Note that the Endevor API was designed to be a batch-oriented service. It is a file-based interface, not a record-based interface. That is, an object is moved from an Endevor-managed repository, to a specified work file; or vice-versa. Mainframe Access will dynamically create the necessary files as required. A transaction history log is likewise written to a log file. Mainframe Access may optionally be configured to retain a full Endevor transaction log to be used as an audit trail. Access to the Endevor interface is serialized since Endevor does not support concurrent accesses from the same address space. At the same time, all Endevor user exits and packages are operational. This means that site customization will affect the response time for an end-user accessing Endevor data under Mainframe Access. This may require adjustments to the timeout parameters on the clients.

Since all data movement is facilitated through temporary files, Mainframe Access is not able to support the Dsname Validation feature of Endevor. The temporary file used by Mainframe Access is deleted as soon as the transaction (Import or Export) ends. For those sites employing this feature, users could use the Endevor dialog tools under TSO to move their members into their own PDS. Then Mainframe Access could be used to move the PDS member from the mainframe to the workstation, and vice-versa. A subsequent promotion to Endevor would then indeed come from the exact same PDS that received the file at sign-out.

Mainframe Access does maintain the user ID security context for each active thread using the standard IBM security environment and standard SAF calls. Mainframe Access will always invoke the Endevor API interface using the security credentials of the end-user as provided during client logon. To minimize some administrative overhead, Micro Focus recommends the adoption of an Alternate RACF user ID to simplify the administration of RACF access rights for the user population. Access security remains a SITE responsibility. This is no different than standard BATCH or TSO access under Endevor. Mainframe Access will not schedule any Endevor access using the Mainframe Access started-task profile. Also be mindful that some change control "processors" might better be managed by specialist personnel using the Endevor ISPF panels rather than being triggered repeatedly by online Mainframe Access users.

Endevor support is available for R14 and later.

Parent topic: Endevor


References

  • Endevor Administration Guide
  • Endevor API Guide
  • Endevor Error Codes and Messages
  • Endevor Exits Guide
  • Endevor Footprints Guide
  • Endevor Installation Guide
  • Endevor Packages Guide
  • Endevor Security Guide
  • Endevor User Guide
  • Endevor Utilities Guide
Parent topic: Endevor


Endevor Dependent Regions

In order to isolate the Endevor run-time environment from the Mainframe Access address space, and improve the concurrency (and hence scalability) of Endevor accesses, Mainframe Access will schedule the execution of the Endevor API in an independent processing region referred to as an Endevor Dependent Region. This is a special purpose address space that Mainframe Access creates dynamically and shares with all Mainframe Access/Endevor users. It is serially assigned to whatever thread is in need of Endevor API services.

Multiple Endevor dependent regions may be started to meet your throughput requirements. The sample SERVERS member contains a definition for an Endevor address space group that allows a maximum of 2 address spaces to be started for Endevor processing. This value can be increased if the demands of your Endevor usage will benefit from greater concurrency.

You will need to update the started task JCL for dependent regions before you can use the Endevor support. Review the sample JCL member MFAAS and follow the instructions in that member to add your Endevor AUTHLIB and CONLIB program libraries to the STEPLIB concatenation. If you use Processor Groups to compile and relink automatically, specify DYNAMNBR=300 on the EXEC statement and eliminate the pre-allocation of SYSPRINT and SYSTERM which conflict with Endevor procedures to allocate compile and link output files.

For those sites where the logged in users may not have the authority to create transient files using their USERID as the high-level qualifier, there is a configuration parameter to set that high-level qualifier to some other value where all users have READ/WRITE/ALTER access.

DSNQUALIFIER_ENDEVOR=prefix         --- OVERRIDE FOR ENDEVOR ACCESS

This must be specified within the configuration parameters specified by DD=XDBIN both in the MFA Control region, and the MFA Endevor Dependant Region.

In addition, the Endevor Dependent Region will automatically shutdown after a pre-defined idle period. The default is 30 minutes. This automatic shutdown feature allows Endevor resource allocation to quiesce with non-use, and thereby permits overnight backups to run without manual intervention. This idle period is defined as two scan intervals as specified in the Dependent Region parameter file:

DSS_SCAN_INTERVAL=15                --- idle timeout for shutdown

By default, the Endevor Dependent Region will create a new VIO file (DDNAME=ENDVMSG) to be used as the Endevor transaction log for all subsequent transactions within that dependent region. The DCB attributes are:

PS,FBA,LRECL=133,UNIT=VIO,DISP=(NEW,DELETE),DSN=&MSGLOG

This file will effectively be a memory resident file, buffered by JES. Note that during initialization there is no end-user profile in effect. That means the VIO file will be owned by the started task. Therefore, the started task security profile must allow any end-user to write to this file. Endevor will OPEN the file as the transaction log. This behavior can be taken as the default, or specified by:

VIO_FOR_ENDEVOR_LOG=YES          default VIO

If this causes a security violation at your site, you may configure the log to be disk-resident, provided the high-level qualifier will allow universal READ/WRITE access to the log. To override the default, use:

VIO_FOR_ENDEVOR_LOG=N            use DISK

Now Mainframe Access will supply overrides to disk as follows:

UNIT=SYSALLDA,DSNAME=prefix.jobname.ASnnnnn.MSGLOG

where the jobname and address space number will ensure uniqueness. The prefix will be taken from the DSNQUALIFIER_ENDEVOR described above.

Parent topic: Endevor


Endevor C1DEFLTS File

It may be necessary to modify the C1DEFLTS table to facilitate the Endevor support in a multi-user environment. If you do modify the C1DEFLTS table, the resulting C1DEFLTS load module should be stored in the STEPLIB of the MFA server start-up JCL to allow for a custom usage. Your Endevor administrator will have the current C1DEFLTS source and corresponding JCL.

The following C1DEFLTS table change is required:

  • The BATCHID= parameter must be 1. This permits signout and security accesses to be based on the security profile of the user, not the MFA Server started task.
C1DEFLTS TYPE=MAIN,
         ACCSTBL=,       ACCESS SECURITY TABLE           X
         APRVFLG=N,      APPROVAL PROCESSING (Y/N)       X
         ASCM=0,         ASCM CONTROL PASSWORD           X
         BATCHID=1,      BATCH UID FROM JOBNAME/USER=    X
         CIPODSN=,       CCID VALIDATION DSNAME          X
          .
          .
          .
          .
C1DEFLTS TYPE=END
END
Parent topic: Endevor


Endevor Setup Errors

Several environmental conditions are validated when the first transaction is processed on an Endevor Dependent Region. Failure to provide a consistent run-time environment will result in the following abends:

Abend | Description
996 | MFAS startup error - no DSS environment found
997 | Endevor DR setup error - no MSGLOG established
998 | Endevor version mismatch between CR and DR
999 | No Endevor support found in STEPLIB or JOBLIB
Parent topic: Endevor


ChangeMan ZMF

Serena's ChangeMan ZMF is a comprehensive mainframe specific solution that provides reliable, streamlined implementation of changes in z/OS environments. Its version, build and release management functions can be used to manage system changes from development to deployment.

  • About ChangeMan ZMF
  • Customization
  • References
  • AppMaster Builder Support using APS Components
Parent topic: Configuring Access to External Library Management Systems


About ChangeMan ZMF

ChangeMan ZMF 5.3 introduced the Serena XML Services, an open interface for interoperability and data interchange with ChangeMan ZMF. This new interface is intended to replace the RPC and API interfaces that were used with earlier releases of ChangeMan. Mainframe Access Server implements the ChangeMan functions using the XML Services interface.

Mainframe Access requires ChangeMan Version 5.5.6 or later.

Parent topic: ChangeMan ZMF


Customization

The customizations required in Mainframe Access Server are simple and deal primarily with defining the interface to the ChangeMan ZMF subsystem. There are four MFA Server startup parameters for defining this interface and they are described in detail below. The parameters are also documented in the section Editing Mainframe Access Parameters in the chapter Configuration.

The Server's ChangeMan interface uses Mainframe Access Application Server address spaces (also known as dependent regions) to provide isolation for the ChangeMan processing. Separating the processing from the MFA Server control region avoids potential interference with other client requests being processed in the control region.

Both the control region and the dependent region(s) have startup parameter requirements for the ChangeMan interface definition. The sample control region parameters are found in member PARMS and the sample dependent region parameters are found in member PARMSAS. Review the startup parameter information in the sections that follow and update your parameter definitions with values appropriate for your installation.

  • Control Region Startup Parameters
  • Control Region Started Task JCL
  • Dependent Region Startup Parameters
  • Dependent Region Started Task JCL
Parent topic: ChangeMan ZMF
Related information
Editing Mainframe Access Parameters


Control Region Startup Parameters

CHANGEMAN_ASGROUP Specifies the name of the MFA Server address space group used to process all ChangeMan requests. The SERVERS sample defines an address space group named CGMQ that is shared by ChangeMan definitions. If you use both features of MFA Server it is possible, but not necessary, to create separate ASGROUP definitions.

The ASGROUP definition in the SERVERS member names a JCL procedure used to initiate the dependent region started tasks. MFA Server provides a procedure named MFAAS that serves as the basis for all dependent-region JCL procedures. You customize and add this JCL to a system procedure library during server installation. Some features of the MFAAS JCL procedure appear as JCL comment statements that you can customize yourself, including symbolic parameters and STEPLIB program library names. You can also customize any of several specialized ChangeMan DD statements in the procedure. The MFAAS JCL contains text that explains all required customizations for ChangeMan.

Specify the one- to four-character ASGROUP name to associate with ChangeMan processing. If you omit this parameter the address space group name defaults to CALL.

CHANGEMAN_COMMON_BUILD | Specifies whether or not Mainframe Access accommodates group builds submitted under AppMaster Builder. Specify YES to enable group builds or NO to disable them. The default is NO. When enabled for group builds, MFA modifies the build options for each member of the AMB group to match the component name and type submitted, ensuring that each build request in the group is properly executed.
CHANGEMAN_DSNQUALIFIER Specifies a high-level qualifier for dynamically allocated data sets created by MFA Server to hold input files during the staging process. MFA Server creates these data sets dynamically as card-image sequential data sets that are deleted when the associated client request completes. The default qualifier is the login ID of the current user. You should set an alternate qualifier if your installation's SERNET does not have RACF authority to read or write data into files stored in data sets named with the current user's login ID as the high-level qualifier.

If an alternate qualifier is required, see your ChangeMan administrator or your security administrator for assistance in selecting a proper value.

If your ChangeMan functionality is restricted by security subsystem authorizations, you might need to specify your dataset high-level qualifier such that read access to the data sets is always permitted.

CHANGEMAN_INTERFACE Specifies the name of the ChangeMan ZMF module. During ChangeMan request processing, MFA Server loads and branch enters this module. Valid values are SERXMLBC and SERXMLAC. The default is SERXMLAC.

The preferred interface module is SERXMLAC, which is not documented by Serena; however, it provides better interface performance than SERXMLBC by using virtual storage instead of data sets for XML input and output exchange between MFA Server (the requester) and ChangeMan ZMF.

Serena documents only the SERXMLBC interface, which is the XML services batch client. SERXMLBC is intended for use in a batch job stream and requires XMLIN and XMLOUT DD statements to define its required data sets. The MFAAS JCL sample provides sample DD statements for XMLIN and XMLOUT; however, they are commented out. If you must use SERXMLBC, contact SupportLine for assistance with data set definitions.

This parameter is required in both the PARMS member and the PARMSAS member used by application server address spaces.

CHANGEMAN_SSID Initializes the Mainframe Access ChangeMan interface by providing the final character of the z/OS subsystem ID used to identify ChangeMan. Omit this parameter to bypass Mainframe Access initialization for the ChangeMan interface. Valid values are any single alphabetic or numeric character. The character specified is appended to the subsystem ID string "SER", completing the four-character ID. For example, if you specify CHANGEMAN_SSID=A, the z/OS subsystem ID becomes "SERA".

This parameter is required in both the PARMS member and the PARMSAS member used by application server address spaces.

Your ChangeMan administrator can help you to determine the correct subsystem ID to use.

CHANGEMAN_TEST_OPTION | Specify whether or not MFA uses the XML trace option. Specify YES to enable XML trace or NO to disable it. The default is NO. When enabled, SERNET logs information in XML format into the standard SERPRINT DD file. This file can be used to identify problems and to validate MFA services. Enabling XML trace is not recommended for production systems due to the large volume of log data generated.
CHANGEMAN_XMS_SIZE | Specifies the size in megabytes of the cross-memory buffer used by MFA for transmitting XML requests and responses to the ChangeMan dependant Region. A single integer in the range of 1 through 7 is accepted. Note that about 2500 directory entries, or 10,000 lines of source code may be passed in 1 megabyte. If your requirements exceed these limits, then you can configure a more appropriate value. The default value with no configuration is 1 megabyte.
Parent topic: Customization


Control Region Started Task JCL

You can customize the sample JCL procedure for the MFA Server started task with required and optional DD statements for the ChangeMan interface.

  • CMNOPTS
  • CMNLIB$
  • CMNJOB$
Parent topic: Customization


CMNOPTS

Include and customize this DD to provide MFA with your site-dependent user options and your default build options. MFA reads the XML file you specify, using only the options defined for field names that correspond to build and user options. These options enable MFA to properly check out and stage ChangeMan components. See your Serena documentation for ZDD Build Options for more information.

//CMNOPTS DD  DSN=youroptions.xml,DISP=SHR

Where youroptions represents a filename prefix of your choice.

The following is an example of an XML file containing user and build options:

<?xml version="1.0"?>
<options name="BUILD">
 <profile application="*" language="*" procname="*" libtype="*">
  <field name="Language"       editable="Y" default="CBL"/>
  <field name="BuildProc"      editable="Y" default="CMNCOB2/>
  <field name="Db2PreCompile"  editable="Y" default="N" />
  <field name="Db2Subsystem"   editable="Y" default="DSN7" />
  <field name="CompileOptions" editable="Y" default="RENT,LIST,XREF(SHORT)" />
  <field name="LinkOptions"    editable="Y" default="RENT,MAP,XREF" />
  <field name="UserOption01"   editable="Y" default="N"
     tag="Compile only"  required="Y"  validation="YN"   />
  <field name="UserOption02"   editable="Y" default="N"
     tag="IMS DLIT entry"  required="N"  validation="YN"   />
  <field name="UserOption03"   editable="Y" default="N"
     tag="CICS precompile"  required="N"  validation="YN"   />
  <field name="UserOption04"   editable="Y" default="N"
     tag="Drop INCLUDEs"  required="Y"  validation="YN"   />
  <field name="UserOption05"   editable="Y" default="N"
     tag="Easytrieve"  required="Y"  validation="YN"   />
  <field name="UserOption06"   editable="Y" default="N"
     tag="AMB Generation"  required="Y"  validation="YN"   />
 </profile>
</options>

The user build options tags <UserOptionnn> support a special keyword for validation. If the valuation="text" corresponds to a reserved keyword as described by Serena, then a generic test will be made for NUMERIC, ALPHABETIC, or ALPHANUMERIC text. Otherwise, the "text" characters themselves will be become the customized set of characters to be used as the validation string. Only a character found in this string will be allowed to act as the User Option value.

Parent topic: Control Region Started Task JCL


CMNLIB$

Optionally include and customize this DD to enable MFA to determine which component types are buildable, depending on the language type and build procedures specified. This not only identifies which Library types Drag & Drop may build, but also provides default language names for new components which have have no component history which would otherwise provide this information.

//CMNLIB$ DD  DSN=your.MFA30.CNTL(CMNLIB$),DISP=SHR

Where your is a dataset qualifier representing the location of the dataset.

The following is the default data:

*  ChangeMan Library Table (fixed format)
*          Like Source only
* L
* I BLDPROC  LANGUAGE
* B  NAME     Name
*** ******** ********
ASM CMNASM   ASM
COB CMNCOB2  COBOL
APS DGSAPCOM COBOL
ASC DGSAPSCR COBOL
Parent topic: Control Region Started Task JCL


CMNJOB$

Optionally include and customize this DD to define up to four job cards ChangeMan can submit for a build request, which is scheduled as an independent job by SERNET as part of the staging process.

//CMNJOB$ DD DSN=your.MFA30.CNTL(CMNJOB$),DISP=SHR

Where your is a dataset qualifier representing the location of the dataset.

The default job card contains:

//useridB  JOB (MFA),'CMN-BUILD',CLASS=A,MSGCLASS=X
//*
//*
//*
Parent topic: Control Region Started Task JCL


Dependent Region Startup Parameters

MFA supports the following dependent region startup parameters for ChangeMan:

  • CHANGEMAN_INTERFACE
  • CHANGEMAN_SSID

Both of these parameters are also control region parameters. When you specify the same parameter for both the control and dependent startup regions, their values must match.

Parent topic: Customization


Dependent Region Started Task JCL

The MFAAS sample JCL procedure contains JCL statements you must customize and enable for the ChangeMan interface. The preceding discussion of the CHANGEMAN_ASGROUP parameter highlights the required changes. If you update sample JCL in the MFA Server samples data set, be sure to copy it to the system procedure library.

Parent topic: Customization


References

  • Serena XML Services User Guide
  • ZMF Administrator Guide
  • ZMF Messages Guide
Parent topic: ChangeMan ZMF


AppMaster Builder Support using APS Components

ChangeMan contains an optional feature for managing APS file types in a ChangeMan application. This support is incompatible with the AppMaster Builder support for APS components as provided by Micro Focus as it does not allow you to over-ride the Build procedures to invoke the AppMaster Builder Generation process.

As a result, when configuring ChangeMan for use with applications and packages used by AppMaster Builder, ChangeMan Administration should not configure the file types using the Selectable Option column, as shown in the following screen shot from the ChangeMan Administration Panels under TSO:

--------------------- WAC4 - LIBRARY TYPES PART 1 OF 2 ----------- Row 1 of 65
 COMMAND ===>                                                  SCROLL ===> PAGE

 Enter END command to save changes or CANCEL to exit.
 Enter * in line command field for global staging libraries selection list.

      LIB                                               LIKE  DEFER TARGET SEL.
      TYPE DESCRIPTION                               (S/C/L/P)(Y/N)  TYPE  OPT.
 '''' COB  Cobol_______________________________________  S     Y     LOD   __
 '''' CPY  Copy Books__________________________________  C     Y     ___   __
 '''' JCL  Job Control Language________________________  P     Y     ___   __
 '''' CTC  Control cards_______________________________  P     Y     ___   __
 '''' LOD  Load Library________________________________  L     Y     ___   __
 '''' ACI  APS COBCICS_________________________________  S     Y     LCI   __
 '''' ACN  APS APSCNTL_________________________________  P     Y     ___   __
 '''' ADA  APS APSDATA_________________________________  P     Y     ___   __
 '''' ADE  APS APSDE___________________________________  P     Y     ___   __
 '''' ADG  APS COBDLG__________________________________  S     Y     LDG   __
 '''' AEX  APS APSEXPS_________________________________  P     Y     ___   __
 '''' AFE  APS APSSCFE_________________________________  P     Y     ___   __
 '''' AID  APS COBIDMS_________________________________  S     Y     LOD   __
 '''' AIM  APS COBIMS__________________________________  S     Y     LIM   __
 '''' AIO  APS APSCNIO_________________________________  P     Y     LOD   __
 '''' AIS  APS COBISPF_________________________________  S     Y     LOD   __
 '''' AMA  APS APSMACS_________________________________  C     N     ___   __
 '''' AMS  APS AMSERV__________________________________  P     Y     ___   __
 '''' AMV  APS COBMVS__________________________________  S     Y     LOD
Parent topic: ChangeMan ZMF


Configuring Access to Enterprise Server Mainframe Subsystem Support

Mainframe Subsystem Support (MSS) is an Enterprise Server feature that provides an execution environment for CICS transaction programs on Windows and UNIX platforms. These programs can be ones migrated from the z/OS platform, or entirely new applications, developed specifically for the Enterprise Server MSS environment.

Mainframe Access runs on z/OS and functions as middleware, providing a transparent bridge between your ES/MSS systems and your z/OS CICS systems and enabling a full range of peer ISC communications between these systems including transaction routing, function shipping, distributed program link and distributed transaction processing. The configuration elements in MFA Server create the relationship between MSS and CICS and enable MFA Server to convert between MSS's TCP/IP-based protocol and CICS's LU6.2-based ISC protocol.

This section presents a step-by-step approach to completing the Mainframe Access Server customizations for ES/MSS support. Use this section to work through the customizations.

  • Prerequisites
  • MFA Server Configuration for ES/MSS
  • Technical Details
Parent topic: Configuring and Administering the Mainframe


Prerequisites

Be sure to complete the basic configuration and installation testing of your Mainframe Access Server before you start the advanced configuration activities for ES/MSS support. See the section Quick Configuration in the Configuration chapter for information on the basic configuration. The configuration described in this appendix assumes that you have completed all of the quick configuration steps that establish your parameter file, server definitions, JCL procedures, etc. Also complete the installation verification testing to ensure that you have a running configuration.

Parent topic: Configuring Access to Enterprise Server Mainframe Subsystem Support
Related concepts
Quick Configuration
Advanced Configuration Activities
Related information
Quick Configuration


MFA Server Configuration for ES/MSS

The diagram below shows a single MSS to CICS connection. The MFA Server configuration statements that enable this bi-directional connection are highlighted in the diagram. Keep in mind that there are corresponding configuration requirements in MSS and CICS, and the entire configuration relies on the communications infrastructure provided by your TCP/IP stack and VTAM SNA server.

ES/MSS runs on a Windows or UNIX platform and is connected to your z/OS system by TCP/IP communications. The other software elements reside on a z/OS platform(s). MFA Server runs on z/OS and functions as middleware, providing a transparent connection between ES/MSS and the CICS system. MFA Server is normally installed on the same z/OS system as CICS, although this is not a requirement. The connection between MFA Server and CICS uses standard CICS ISC LU6.2 protocols and MFA Server and CICS may reside in different systems on your SNA network. ES/MSS and MFA Server participate in the TCP/IP network by starting socket listeners, and by accepting and originating socket connection requests. CICS and MFA Server participate in the VTAM SNA network as Logical Units (LUs) by creating and opening a VTAM Access Method Control Block (ACB), and by allocating and managing LU6.2 conversations.

The MFA Server configuration is easy. There are three distinct parts to the configuration, numbered 1, 2, and 3 in the diagram. Part 1 is a simple enabling, or activation, statement. Part 2 defines your z/OS CICS system and provides the information needed for a VTAM SNA connection to this system. Part 3 defines your ES/MSS system and provides the information needed for a TCP/IP connection to this system. All of these statements can be found in the PARMS (Part 1) and SERVERS (Parts 2 and 3) members of your MFA Server <hlq>.CNTL data set. The definitions shown here for ES/MSS and CICS are two of the actual samples from that data set. When you understand the configuration requirements and have determined the correct values for your systems, complete your configuration using a text editor to update these sample definitions with your values. There is no pre-processor or configuration utility used with the MFA Server definitions and there is no configuration information maintained by MFA Server across restarts. So, each time MFA Server is started, your current definitions will be read in during start up, processed and activated. If you need to make changes during your testing, simply update the configuration statements and restart MFA Server.

The following subsections describe the customizations needed for your ES/MSS - CICS connection. The discussion refers to sample definitions that are provided by MFA Server installation and if this is your first ES/MSS configuration it will be easy to update the sample definitions as described.

  • Enable ES/MSS Support
  • Define the Target z/OS CICS System
  • Define the Target ES/MSS Server
  • Restart MFA Server
Parent topic: Configuring Access to Enterprise Server Mainframe Subsystem Support


Enable ES/MSS Support

Your PARMS member in the MFA Server <hlq>.CNTL data set contains the ES/MSS OUTBOUND FEATURE parameter setting. This parameter is set to NO in the sample member. Change the setting to YES. This activates ES/MSS support the next time Mainframe Access Server is started. This specification directs MFA Server to activate the outbound feature and process other definition statements for the MSS feature. Without the YES specification the related ES/MSS server definitions (number 3 in the diagram) are ignored during start up.

*--------------------------------------------------------------------*
* Services to be activated                                           *
*--------------------------------------------------------------------*
*
TCP LINK FEATURE=YES           --- SQL Option, Telnet client
MFADIRECT=YES                  --- Mainframe Access services
MFA FEATURE=YES                --- Mainframe Access Data Connect Server
PEM FEATURE=YES                --- Password Expiration Manager
MCO FEATURE=NO                 --- CICS Option
REMOTE IMS FEATURE=NO          --- IMS Option
LIST DB2=NO                    --- DB2 and IMS subsystem finder
ES/MTO OUTBOUND FEATURE=YES    --- ES/MTO Outbound support
Parent topic: MFA Server Configuration for ES/MSS


Define the Target z/OS CICS System

Your SERVERS member in the MFA Server <hlq>.CNTL data set contains two sample CICS server definitions, one being the CICA sample shown here.

<MCOID=CICA>
LUNAME=CICSSYSA
TPNAME=*
MODENAME=#INTER
SYNCLEVEL=0
SECURITY=NONE
<END>

Parameter | Description
<MCOID=CICA> | Identifies the start of a z/OS CICS target server definition and provides the SYSID value for that server. Change this value to the SYSID of your z/OS CICS system. Specify the same SYSID when you define this CICS to your ES/MSS server in a connection definition.
LUNAME=CICSSYSA | Provides the SNA LU name (also referred to as the VTAM ACB name or VTAM APPL name) of your CICS system. Change the value to the LU name of your CICS system.
TPNAME=* | Identifies the transaction program name used in LU6.2 requests. The actual transaction program name used in each LU6.2 request depends on the function that is requested, and the value is supplied by the system that originates a request. MFA Server adapts depending on the value supplied. Leave this parameter as-is.
MODENAME=#INTER | Provides the name of the VTAM SNA logmode used for LU6.2 sessions. If necessary, change the value to the name of the VTAM SNA logmode you want to use for your LU6.2 sessions. This same logmode name should be used in your CICS SESSIONS definition for the ES/MSS server.
SYNCLEVEL=0 | Sets the synchronization level for LU6.2 requests and is supplied by the system that originates a request. MFA adapts depending on the value supplied. Leave this parameter as-is.
SECURITY=NONE | Sets the security level for LU6.2 requests and is supplied by the system that originates a request. MFA adapts depending on the value supplied. Leave this parameter as-is.
<END> | Marks the end of the definition.
Parent topic: MFA Server Configuration for ES/MSS


Define the Target ES/MSS Server

Your SERVERS member in the MFA Server <hlq>.CNTL data set contains two sample ES/MSS server definitions, one being the MSS1 sample shown here.

<ES/MTOID=MTO1>
ACBNAME=MFAMTO1
IPADDRESS=YOUR.MTO.HOSTNAME
PORT=2200
SESSIONS=4
SOCKETS=1
<END>
Parameter | Description
<ES/MTOID=MTO1> | Identifies the start of an ES/MSS target server definition and provides the ES/MSS SYSID needed to identify the ES/MSS system to MFA Server. Change this value to the SYSID of your ES/MSS server. Specify the same SYSID for the CONNECTION(name) when you define this ES/MSS server to your z/OS CICS system.
ACBNAME=MFAMTO1 | Assigns a VTAM ACB name (also referred to as the SNA LU name or VTAM APPL name) to the ES/MSS server. You can define more than one ES/MSS server and each server you define must have its own ACBNAME, giving it a unique identity in the z/OS CICS system. MFA Server provides two VTAM APPL definitions for ES/MSS servers - MFAMTO1 and MFAMTO2. These are installed and activated in your VTAM SNA configuration during MFA Server installation. If you are defining only one ES/MSS server, leave the ACBNAME as MFAMTO1. Use the MFAMTO2 ACB name if you define a second server. To define more than two ES/MSS servers, you must first install additional VTAM APPL definitions.
IPADDRESS=YOUR.MTO.HOSTNAME | Identifies the internet address of your ES/MSS server machine. Change this value to either the machine name of the server where you're running ES/MSS or the internet IP address of the server.
PORT=2200 | Identifies the TCP/IP port on your ES/MSS server that has been configured as an ISC listener. Change this value to the the ISC listener PORT number on your ES/MSS server.
SESSIONS=4 | Identifies the maximum number of transaction processing sessions that will be managed on a single socket connection. Each active LU6.2 conversation requires a session and the session traffic is interleaved on the MSS to MFA socket connection. For testing purposes, leave this value as-is. However, you might need to adjust it upwards to satisfy your installation's demand as usage increases.
SOCKETS=1 | Identifies the number of sockets available for each MSS to CICS connection. Because ES/MSS requires a single socket for each connection to CICS, leave this value as-is.
<END> | Marks the end of the definition.
Parent topic: MFA Server Configuration for ES/MSS


Restart MFA Server

When you complete the configuration steps, save your updated definitions and restart your MFA Server to activate the definitions. Be sure to complete the related configuration activites in ES/MSS and z/OS CICS before you begin testing.

Parent topic: MFA Server Configuration for ES/MSS


Technical Details

The more detailed tecnical information in this section will increase your understanding of the configuration requirements. You will also be better prepared to respond to operational issues that may arise during the testing of this feature.

  • How ES/MSS Understands the Connection
  • How z/OS CICS Understands the Connection
Parent topic: Configuring Access to Enterprise Server Mainframe Subsystem Support


How ES/MSS Understands the Connection

The communication between ES/MSS and MFA Server uses a proprietary TCP/IP protocol that conveys the necessary LU6.2 protocol information in TCP/IP packets. The SYSIDs used in the MFA Server configuration are the key to this communication. In the example definitions, the target z/OS CICS system is identified as CICA and the target ES/MSS server is identified as MTO1. The initial connection messages between ES/MSS and MFA Server use these SYSID values to exactly identify the two target systems.

If ES/MSS initiates the socket connection to MFA Server, ES/MSS will send a "bind" packet for SYSID CICA. The bind packet also contains the SYSID of the originating MSS, MTO1. The initial packet from ES/MSS is identical to the initial packet from a CICS support client, so MFA Server needs to identify the type of requester. If MFA Server finds a definition for an ES/MSS server with a SYSID of MTO1 (the ES/MTOID in the definition) and the request originated from the IP address specified in that definition, then MFA Server recognizes this as a request from an ES/MSS server. Otherwise, the connection is recognized as a request from a CICS support client.

At this point, it is important to note that support for CICS has been available in earlier versions of MFA Server and this support allows MFA Server clients to originate requests INTO a z/OS CICS system. This same level of support has also been used by ES/MSS systems, before the availability of the ES/MSS outbound feature. This level of support does not require a definition for the ES/MSS server and it does not require the ES/MSS outbound feature support. In this case, the only definition required is the definition of the target z/OS CICS system (number 2 in the diagram) and the activation of the MFA Server CICS support (using the PARMS statement MCO FEATURE=YES). If your only need is for ES/MSS requests into CICS, you may continue to configure your MFA Server in this way. However, our recommendation is that you follow the configuration requirements as outlined in this appendix and define a complete bi-directional connection for the systems that uses MFA Server's ES/MSS outbound feature. The extra effort is minimal and your systems will be ready to support CICS requests into ES/MSS, when they are needed. The complete configuration also results in each ES/MSS having a unique identity from the perspective of the z/OS CICS systems.

Once the initial connection is established, the ES/MSS and CICS definitions have been selected and MFA Server has all of the information it needs to accept a request from ES/MSS and send it into z/OS CICS over an LU6.2 ISC connection. MFA Server will allocate LU6.2 conversations using the MFAMTO1 ACB that has been defined for this ES/MSS. The conversation partner will be the z/OS CICS system that is using the ACB named CICSSYSA and the SNA session for the conversation will use the #INTER SNA logmode. The VTAM SNA logmodes are part of your VTAM SNA configuration and the suggested name can be changed to any other logmode name used for LU6.2 ISC connections in your system. Just be sure that the specified logmode definition is available to both MFA Server and CICS. The MFAMTO1 ACB name used in this sample definition is defined to the VTAM SNA network using a VTAM APPL definition. The APPL definition for MFAMTO1 is provided in another MFA Server sample, the MFAVTAM member in your <hlq>.CNTL data set. This member is installed in your VTAMLST definitions and activated during MFA Server installation.

Each ES/MSS server that you define must have its own ACBNAME and it is this ACBNAME that gives each server a unique identity in the z/OS CICS system(s).

Parent topic: Technical Details


How z/OS CICS Understands the Connection

The communication between z/OS CICS and MFA Server uses standard LU6.2 ISC protocol as implemented by CICS. The SNA logical unit names used in the MFA Server configuration are the key to this communication. In the example, the target z/OS CICS system is identified as CICSSYSA (LUNAME=CICSSYSA) and the target ES/MSS server is identified as MFAMTO1 (ACBNAME= MFAMTO1).

Our target z/OS CICS initiates work to ES/MSS when a request is directed to an external CICS SYSID that is associated with the MFAMTO1 LU name by CICS definitions. A CICS CONNECTION defines the MFAMTO1 LU name and assigns an external SYSID. A CICS SESSIONS definition for that connection defines the SNA logmode to be used for the ISC conversations. It is important to note that the SYSID values known to z/OS CICS do not have to match the SYSID values known to MFA Server and ES/MSS, however, MFA Server and ES/MSS must agree in their definitions. Although the SYSID values known to CICS can be different from the ES/MSS and MFA Server definitions, we recommend that the same SYSID values be used throughout the definitions.

CICS handles the request to the external SYSID by establishing the LU6.2 sessions that support the ISC exchanges, if they are not already established. CICS then sends the initial FMH-5 Attach request for the conversation to MFAMTO1. MFA Server recognizes this request as a conversation for ES/MSS because CICS used the MFAMTO1 LU name. MFA Server also checks that the request originated in a defined CICS server by locating the definition for the originator's LU name (CICSSYSA) and logmode name (#INTER) combination. Having located the two sets of definitions, MFA Server can forward the request on to the target ES/MSS server. If there is currently no socket connection to ES/MSS, MFA Server has the IP address and port number needed to contact ES/MSS's ISC listener. Now the request can be forwarded to ES/MSS over the socket connection associated with the MTO1-CICA SYSID combination.

Parent topic: Technical Details


Configuring the Enterprise Server Environment

The information in this section covers configuring Enterprise Server to connect to a mainframe.

  • Configuring the Environment
  • Configuring Server Access
Parent topic: Configuring and Administering the Mainframe


Configuring the Environment

To configure the mainframe to PC environment, you need to set up the mainframe node or nodes that the PC environment will connect to and use.

You can also configure:

  • Environment variables to configure the various aspects of the system.
  • How embedded hex values are handled in files that are transferred.
  • Configuring Environment Variables
  • Handling Embedded HEX Values
Parent topic: Configuring the Enterprise Server Environment


Configuring Environment Variables

The Drag and Drop applications check for optional environment variables to have been specified. These variables allow certain configuration information to be designated.

The environment variables that you can configure are:

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
MFAMAXSENDLENGTH | Sets the maximum length of data, in a single communication packet, that can be transmitted to or from the mainframe. This does not affect the size of the file that can be transmitted, but only the size of each of the numerous data chunks that are transmitted to make up the entire file. This is only useful, when there is a router that limits the transfer length of data to or from the mainframe, or there is a restriction in the length of data that can be transferred. Example: SET MFAMAXSENDLENGTH=4000
MFAMAXHOTLINKS | If using the hot-link software from Micro Focus, the LSC applications will route all communication request through this hot-link. The hot-link remains active to the mainframe until you shut down your workstation, or enter the command MFDAELSC CLOSE. The hot-link is able to allocate and load balance more than multiple simultaneous links and will start up an additional link if any request has to wait for more than 15 seconds for a time slice. The maximum number of simultaneous links can be specified, with a default of 4 and a maximum of 10, as follows: SET MFAMAXHOTLINKS=4
MFAIMBEDDEDHEX | Indicates that you wish to have all source code embedded hex values handled in the same way as the MDECONV application, in that all translated hex values less than x'1f' will have a null character inserted before the hex value. The COBOL run-time system will properly handle these imbedded hex values. Example: SET MFAIMBEDDEDHEX=COBOL
Parent topic: Configuring the Environment


Handling Embedded HEX Values

Important note: Many mainframe installations own source code that contains embedded hex values. These hex values are handled by Drag and Drop, or Compare and Synchronization Monitor, in two different ways, depending upon your requirements.

  • The first method, the default, is to simply translate these hex values to ASCII and hope that the workstation applications handle them properly.
  • The second method is much more integrated with other Micro Focus applications, and may be the desired technique to be used. This method, will detect all imbedded hex values that translate to less than x'1f' and insert a null byte in front of each of them. This is the Micro Focus MDECONV technique, and all Micro Focus COBOL applications will properly detect this. To turn on this method, you must have set either the use MDECONV style imbedded hex processing in the configure options pulldown of Drag and Drop, or have set an environment variable specified as MFAIMBEDDEDHEX=COBOL. You may also mix applications and techniques if desired. One application environment setup can have this environment variable active, while another application, on the same workstation, can have it turned off.
Parent topic: Configuring the Environment


VSAM Record Length Restrictions

The maximum record length that Drag and Drop, SourceConnect and Compare and Synchronization Monitor can handle is 64,000 bytes. If you have defined a VSAM file with a maximum record length greater than 64,000, then it is still possible that it can be read. It depends upon whether or not a record actually exists in the data set that is longer than the 64,000 byte limit. This limit is actually 63,998 bytes because LSC appends a 2 byte length code.


Configuring Server Access

Use the Server Access Configuration dialog box to configure mainframe access for your MFA components.

  • Configuring the Cache
    Set the location for cached files used by MFA components.
  • Mainframe Connections
    Maintain a list of mainframe connections that you use with certain MFA Components, such as SourceConnect and the Compare and Synchronization Monitor.
  • About MFDaemon
    View the status of the daemon used by the MFA components, and the contents of its configuration file.
Parent topic: Configuring the Enterprise Server Environment


Configuring the Cache

The drive mapping process caches files to a file or folder on your PC. The cache folder is also used to contain a log file detailing any exceptions that occur while accessing the mainframe files.

CAUTION:
You need to ensure that there is sufficient available space on your PC to contain the cache.

To configure the cache location:

  1. On the Server Access Configuration dialog box, select the General tab.
  2. Click Change to display the Browse for Folder dialog box.

    Use the dialog box to browse for and select a folder.

  3. Click OK to set the selected folder as the cache location.
Parent topic: Configuring Server Access
Related information
Adding a Mainframe Node
Configure PVCS Drives
Configure Mainframe Drives


Mainframe Connections

In order to access the files on a mainframe when using components, such as SourceConnect and Compare and Synchronization Monitor, you need to define a mainframe node.

In the Server Access Configuration dialog box, you can configure multiple mainframe nodes, each pointing to different MFA mainframe servers on one or more mainframes.

Server Access Configuration

From this screen, you can also edit and delete these nodes.

Note: Any changes you make in this dialog box affect all mainframe components that use mainframe nodes.
  • Adding a Mainframe Node
  • Editing a Mainframe Node
  • Deleting a Mainframe Node
Parent topic: Configuring Server Access
Related tasks
Starting Compare and Synchronization Monitor from the user interface


Adding a Mainframe Node

  1. To display the Server Access Configuration dialog box, use one of the following options:
    • From the Windows Start menu, click Start > All Programs > Micro Focus Enterprise Developer > Configuration > Mainframe Access Configuration.
    • From the Compare and Synchronization Monitor main screen, on the Options menu, select Mainframe Access Configuration.

    The Server Access Configuration dialog box appears.

  2. In the Server Access Configuration dialog box, click Add.
  3. Enter a name for the mainframe node, then click Next.

    The connection details appear:

  4. In the Logical Server Name field, enter the IP address or DNS name of the mainframe.
  5. Do one of the following:
    • To connect directly to the mainframe, in the Name or IP Address field, enter the name or IP address of the mainframe, and in the Port Number field, add the port number to connect on.
    • To use a CCITCP2 daemon to connect to the mainframe, select Identify a remote computer that is running a CCITCP2 daemon, and if that daemon is on a remote computer, enter the DNS name of that computer. If the daemon is running on your machine, you do not need to enter the computer name.
  6. Click Next.

    A summary of the connection details appears.

  7. Click Finish.
Parent topic: Mainframe Connections
Related concepts
Configuring the Cache
Related information
Editing a Mainframe Node
Deleting a Mainframe Node
Configure PVCS Drives
Configure Mainframe Drives


Editing a Mainframe Node

  1. To display the Server Access Configuration dialog box, use one of the following options:
    • From the Windows Start menu, click Start > All Programs > Micro Focus Enterprise Developer > Configuration > Mainframe Access Configuration.
    • From the Compare and Synchronization Monitor main screen, on the Options menu, select Mainframe Access Configuration.

    The Server Access Configuration dialog box appears.

  2. On the Server Access Configuration dialog box, select the Node tab.
  3. In the list, select the node to edit, and click Edit to display the Node Configuration dialog box.
  4. If you have more than one node configured, and you want to make this node the default node, check Make this the default node.
  5. Click Credentials and set the logon credentials:
    1. Enter the logon details in the User name and Password fields.
    2. In the Expires field, select the duration for which the credentials remain active.
    3. Check Use to authenticate against all resources to use the credentials for all defined nodes.
    4. Check Save to INI file if you want to retain these credentials between sessions. The next time you start a session, MFDaemon checks for the INI file and uses the credentials it contains.
      Note: If you do not save these credentials, components such as SourceConnect prompt you for them each time they require mainframe access.
    5. Click OK.

      The node details appear again.

  6. Edit the Name and Network details, as appropriate, then click OK.

    The node is updated.

Parent topic: Mainframe Connections
Related information
Adding a Mainframe Node
Deleting a Mainframe Node


Deleting a Mainframe Node

  1. To display the Server Access Configuration dialog box, use one of the following options:
    • From the Windows Start menu, click Start > All Programs > Micro Focus Enterprise Developer > Configuration > Mainframe Access Configuration.
    • From the Compare and Synchronization Monitor main screen, on the Options menu, select Mainframe Access Configuration.

    The Server Access Configuration dialog box appears.

  2. On the Server Access Configuration dialog box, select the Node tab.
  3. In the list, select the node to delete, and click Delete.

    The node is deleted.

Parent topic: Mainframe Connections
Related information
Adding a Mainframe Node
Editing a Mainframe Node


About MFDaemon

MFDaemon is a process that runs on your PC to maintain mainframe login access details. With mainframe credentials:
  • When you start a mainframe access session on your PC, MFDaemon checks for an .INI file and loads any login configurations that it contains.
  • When you edit a node to set login credentials for the node, MFDaemon saves these credentials and supplies them as required when access authentication is required.
    Note: Although not encrypted, the password is saved in the .INI file in a non-human-readable format.

You can use the MFACLIENTINI environment variable to set the name of the .INI file. If this variable is not set, the default name and path of the .INI file is:

c:\users\USERNAME\appdata\roaming\micro focus\mfaclient.ini

  • Viewing the status of MFDaemon
Parent topic: Configuring Server Access
Related concepts
Security


Viewing the status of MFDaemon

  1. To display the Server Access Configuration dialog box, use one of the following options:
    • From the Windows Start menu, click Start > All Programs > Micro Focus Enterprise Developer > Configuration > Mainframe Access Configuration.
    • From the Compare and Synchronization Monitor main screen, on the Options menu, select Mainframe Access Configuration.

    The Server Access Configuration dialog box appears.

  2. Click the MFDaemon tab.

    The status of the daemon appears.

  3. To stop or start the daemon, click Stop Daemon or Start Daemon, as appropriate.
    Note: Stopping the daemon will affect all Mainframe Access components.
Parent topic: About MFDaemon


Mainframe Access Messages

Mainframe Access and the z/OS operating system use messages to document both normal and abnormal conditions while Mainframe Access is running. The z/OS system log, the Mainframe Access job log and the Mainframe Access SYSOUT data sets are all possible destinations for important messages about Mainframe Access operation. You should already be familiar with z/OS system messages.

  • Mainframe Access Server Messages
  • Status Codes and Error Messages
Parent topic: Configuring and Administering the Mainframe


Mainframe Access Server Messages

Some Mainframe Access messages are directed to system consoles as specified by the ROUTE Mainframe Access configuration parameter. Other messages are directed to the job log for the started task or to the XDBOUT file (or both). If you experience problems with Mainframe Access operation, it is important that you review the various message destinations for information that may help you diagnose the problem. This section includes an explanation of each of these messages, ordered by message number.

  • Mainframe Access Operational Messages Format
  • Mainframe Access Messages
  • Data Set Services Messages
  • MFA Direct Messages
  • Data Connect Messages
  • Drag and Drop Error Messages
    Error messages relating to Drag and Drop are prefixed MFDAS.
Parent topic: Mainframe Access Messages


Mainframe Access Operational Messages Format

Mainframe Access operational messages are of the form:

mm/dd/yy hh:mm:ss.t taskname taskid MFMnnnna text

or

mm/dd/yy hh:mm:ss.t taskname taskid MFMDSnnna-text

where

mm/dd/yy | indicates the date when the message was issued.
hh:mm:dd.t | indicates the time when the message was issued.
taskname | is the name of the Mainframe Access task that issued the message.
taskid | is a two hexadecimal digit task identifier that helps to uniquely identify the Mainframe Access task for tasks that share a common task name. For instance, task name XDBMFADM processes Mainframe Access Direct client requests and there may be several instances of this task, each managing the work of a different subset of client connections. When examining XDBOUT trace messages for a specific client, trace messages from other clients and their processing tasks may be interleaved with the trace messages for the client that is of interest. The taskid value helps to identify the messages associated with a particular task.
DS | indicates that the message was produced by the Data Set Services (DSS) component of Mainframe Access, which provides all file allocation and record access services.
nnnn | is an integer in the range 0001 through 9999
a | is I if the message is for information only, or E if the message indicates an error condition
text | is the error message text

Messages may be issued that do not have the MFMnnnna or MFMDSnnna message prefix. These messages are diagnostic and/or trace messages that are not documented in this messages section. They are intended for use by Product Support.

Parent topic: Mainframe Access Server Messages


Mainframe Access Messages

MFM0001I:
Mainframe Access version (service) is active

Issued when Mainframe Access initialization completes. version identifies the Mainframe Access product version and service indicates the current maintenance level that has been applied to Mainframe Access.

MFM0001I: Mainframe Access version (service) is active

Issued when Mainframe Access initialization completes. version identifies the Mainframe Access product version and service indicates the current maintenance level that has been applied to Mainframe Access.

MFM0002I: listener socket number is n

Issued during startup by the process that serves client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. This message identifies the socket number n that has been allocated for listening and accepting the client connections.

MFM0003I: getsockopt return code is n

Issued during startup by the process that serves client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. n is the return code from the TCP/IP getsockopt call and a value of zero indicates that startup is proceeding normally.

A non-zero value may indicate a problem. Refer to your TCP/IP provider's socket API return code documentation for an explanation of the non-zero value.

MFM0004I: setsockopt reus return code is n

Issued during startup by the process that serves client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. n is the return code from the TCP/IP setsockopt REUS call and a value of zero indicates that startup is proceeding normally.

A non-zero value may indicate a problem. Refer to your TCP/IP provider's socket API return code documentation for an explanation of the non-zero value.

MFM0005I: setsockopt linger return code is n

Issued during startup by the process that serves client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. n is the return code from the TCP/IP setsockopt call and a value of zero indicates that startup is proceeding normally.

A non-zero value may indicate a problem. Refer to your TCP/IP provider's socket API return code documentation for an explanation of the non-zero value.

MFM0006E: Tcpm socket error, sd=n1, function=name, errno=n2

Issued by the process that serves client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. This process establishes the client connection and then assigns the client to a processing subtask based on the client type (for example, CICS Option client, IMS client, Telnet client). This message indicates that an error has occurred during the processing of a socket API call associated with this connection establishment process. name identifies the specific socket API call, n1 identifies the socket (either the listening socket or a new socket created when a client request is accepted) and n2 is the TCP/IP errno value that was reported for the call.

Refer to your TCP/IP provider's socket API return code documentation for an explanation of the errno value for the specified function.

MFM0007E: Tcpm socket error, sd=n1, function=name, errno=n2

Issued by the process that serves client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. This process establishes the client connection and then assigns the client to a processing subtask based on the client type (for example, CICS Option client, IMS client, Telnet client). This message indicates that an error has occurred during the processing of a socket API call associated with this connection establishment process. name identifies the specific socket API call, n1 identifies the socket (either the listening socket or a new socket created when a client request is accepted) and n2 is the TCP/IP errno value that was reported for the call.

Refer to your TCP/IP provider's socket API return code documentation for an explanation of the errno value for the specified function.

MFM0008E: Parameter initialization has failed

Issued during initialization if parameters processed from the active configuration data set specified by the //XDBIN data definition statement contain errors that make it impossible for Mainframe Access to complete startup. Mainframe Access shuts itself down after issuing this message.

Review the startup messages to identify and correct any configuration errors before restarting Mainframe Access.

MFM0009E: APF authorization has failed

Issued during initialization if Mainframe Access finds that it is not executing as an z/OS authorized program. Mainframe Access must execute as an z/OS authorized program and the z/OS TESTAUTH service is used to verify this during startup. Mainframe Access shuts itself down with a U2199 abend after issuing this message.

Check each program library name in the //STEPLIB data definition statement and make sure that each is identified to z/OS' Authorized Program Facility as an authorized program library. Common mistakes are misspelled data set names and incorrect DASD volume identifications.

MFM0010E: Global data area initialization failed

Issued during initialization if Mainframe Access cannot load required service modules and initialize its global data areas. Mainframe Access shuts itself down with a U2202 abend after issuing this message.

If you see this message contact our Product Support.

MFM0011I: Mainframe Access shutdown completed

This is the last message issued during shutdown to indicate that all processes have been stopped. The Mainframe Access job or started task should end immediately after issuing this message. If the Mainframe Access stop command is issued and you do not see this message within a reasonable amount of time (approximately 30 seconds) there is most likely a problem quiescing one or more of the Mainframe Access processes. This may be due to a Mainframe Access problem or it may be the result of other problems in the system.

If such a condition occurs frequently and no associated system condition can be identified, contact our Product Support for assistance.

MFM0012I: TCP port number is n

Issued during initialization as parameters are processed from the active configuration data set specified by the //XDBIN data definition statement. n is the TCP port number for client connections, as specified in your Mainframe Access configuration parameter TCP_PORT.

MFM0014I: Mainframe Access version (service) for company

Issued during initialization as parameters are processed from the active configuration data set specified by the //XDBIN data definition statement. version identifies the Mainframe Access product version and company is your company name as specified in your Mainframe Access configuration parameter ORGANIZATION.

MFM0015I: message text

Message MFM0015I is a blank template that is used during the creation of Mainframe Access displays in response to administrative commands. message text is a self-explanatory line of display information created by command processing routines. For examples of how this message is used see the sample command output in the chapter Administration Using Console Commands.

MFM0016E: Tcps socket error, sd=n1, function=name, errno=n2

Issued by the process that serves clients that use DB2 connectivity. This message indicates that an error has occurred during the processing of a socket API call associated with client communication. name identifies the specific socket API call, n1 identifies the client socket and n2 is the TCP/IP errno value that was reported for the call.

Refer to your TCP/IP provider's socket API return code documentation for an explanation of the errno value for the specified function.

MFM0017E Tcps socket error, sd=n1, function=name, errno=n2

Issued by the process that serves clients that use DB2 connectivity. This message indicates that an error has occurred during the processing of a socket API call associated with client communication. name identifies the specific socket API call, n1 identifies the client socket and n2 is the TCP/IP errno value that was reported for the call.

Refer to your TCP/IP provider's socket API return code documentation for an explanation of the errno value for the specified function.

MFM0018I: name-address Task initialization has completed

Issued during startup by Mainframe Access' specialized z/OS processing subtasks as they successfully complete initialization. name identifies the type of subtask and address is the address of Mainframe Access' task control block for the process.

MFM0019I: name-address Task shutdown has completed

Issued during shutdown by Mainframe Access' specialized z/OS processing subtasks as they complete shutdown. name identifies the type of subtask and address is the address of Mainframe Access' task control block for the process. These messages can sometimes help to identify the general nature of a Mainframe Access shutdown delay or failure by identifying the processes that have successfully finished their cleanup procedures.

MFM0020E: Wwwm socket error, sd=n1, function=name, errno=n2

Issued by the process that serves HTTP client requests arriving on the administration port. This process establishes the client connection and then assigns the client to a processing subtask based on the HTTP request (for example, simple resource retrieval of a page or image, or ISPI program request). This message indicates that an error has occurred during the processing of a socket API call associated with this connection establishment process. name identifies the specific socket API call, n1 identifies the socket (either the listening socket or a new socket created when a client request is accepted) and n2 is the TCP/IP errno value that was reported for the call.

Refer to your TCP/IP provider's socket API return code documentation for an explanation of the errno value for the specified function.

MFM0023E: Conversation id returned null for socket blockaddress

Issued by the processes that serve Remote IMS and CICS Option client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. This message indicates that an error occurred when Mainframe Access tried to access the LU6.2 conversation associated with this client's IMS or CICS connection. address identifies the Mainframe Access socket block associated with the requesting client.

If this problem occurs frequently, contact our Product Support for assistance.

MFM0024E: Client data length error, length is 0

Issued by the processes that serve Remote IMS and CICS Option client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. This message indicates that an error occurred when Mainframe Access received a request message from the client.

If this problem occurs frequently, contact our Product Support for assistance.

MFM0025I: Trace set to data level on

Issued in response to the Trace On command to confirm that Mainframe Access activity tracing has been initiated. Trace data is written to the destination specified by the configuration parameter TRACE, or to the default destination, the XDBOUT data set.

MFM0026I: Trace set to data level off

Issued in response to the Trace Off command to confirm that Mainframe Access activity tracing has been stopped.

MFM0027I: Telnet mode on

Issued to confirm that Mainframe Access is accepting Telnet client connection requests.

MFM0028I: Telnet mode off

Issued to confirm that Mainframe Access is not accepting Telnet client connection requests.

MFM0029E: Command is not allowed

Issued to indicate that the previously entered command could not be processed although it was entered correctly.

MFM0030E: name invalid command, please reenter

Issued to indicate that the previously entered command name could not be processed due to an error in the format of the command parameters.

Reenter the command with correct parameters.

MFM0031E: Wtrm task shutdown initiated for unrecoverable error

Issued by the Mainframe Access task that processes operator commands. This message indicates that a severe error occurred during the processing of a command. Commands can originate from the system console (z/OS Modify command) and Telnet clients.

Restart Mainframe Access after shutdown is complete. If this problem occurs frequently, contact our Product Support for assistance.

MFM0032E: Wtrm task is recovered

Issued by the Mainframe Access task that processes operator commands. This message indicates that a severe error occurred during the processing of a command and Mainframe Access was able to resume normal processing. Commands can originate from the system console (z/OS Modify command) and Telnet clients.

If this problem occurs frequently, contact our Product Support for assistance.

MFM0042E: DLL DD name is missing

Issued when a request for an ISPI program is received and Mainframe Access' ISPI program loader cannot find a data definition statement for the ISPI program libraries (the //DLL DD statement). An error response is sent to the requester.

Stop Mainframe Access, add the missing //DLL data definition statements to the Mainframe Access startup JCL and then restart Mainframe Access.

MFM0043E: Open DLL file has failed

Issued when a request for an ISPI program is received and Mainframe Access' ISPI program loader receives an error indication from z/OS when opening the ISPI program libraries identified by the //DLL DD statements. An error response is sent to the requester.

Examine the system log and job log for I/O error messages associated with this failure and use that information to correct the problem. If the problem persists or cannot be identified, contact our Product Support for assistance.

MFM0045E: Unable to allocate LU6.2 conversation with target CICS

Issued by the process that serves CICS Option client requests arriving on the TCP port, as specified in your configuration parameter TCP_PORT. This message indicates that an error has occurred while Mainframe Access was attempting to allocate an LU6.2 conversation to the target CICS region. In some cases the actual error may have occurred during session establishment with the target CICS system and preceding error messages may contain LU6.2 return code information that will be helpful in diagnosing the problem.

Verify that all of the Mainframe Access target server configuration parameters for the CICS region are correct. Also check that the CICS definitions for Mainframe Access are correct and that the VTAM log mode specified in the target server configuration is available to both CICS and Mainframe Access. If this problem occurs frequently, contact Micro Focus Product Support for assistance.

MFM0046E: Function ship error, errno=n, desc=text, data=string

Issued by the process that serves CICS Option client requests arriving on the TCP port, as specified in your configuration parameter TCP_PORT. This message indicates that an error has occurred while Mainframe Access was communicating with the target CICS region. n is an error code assigned by Mainframe Access. text provides a short description of the type of error or the current state of processing. string provides additional error information appropriate for the type of error being reported.

If this problem occurs frequently, contact our Product Support for assistance.

MFM0047I: DSS maximum shared public files is n

Issued during initialization as parameters are processed from the active configuration data set specified by the //XDBIN data definition statement. n is the value specified in the configuration parameter MAX_PUBLIC_FILES. This value indicates the maximum number of shared files that can be concurrently open.

MFM0049I: DLL name scheduled for MFM0049I: DLL name scheduled for refresh

Issued in response to the ISPI module refresh command to confirm that Mainframe Access has accepted the refresh request. A new copy of the requested ISPI load module will be brought into storage using the z/OS LOAD service and used to process subsequent HTTP requests for the program.

MFM0053I: SMF recording is on, record id is n

Issued during initialization as parameters are processed from the active configuration data set specified by the //XDBIN data definition statement. n is the value specified in the configuration parameter SMF_RECORDID. This is a valid user SMF record id and recording is activated.

MFM0054E: SMF recording is off, record id is zero or invalid

Issued during initialization as parameters are processed from the active configuration data set specified by the //XDBIN data definition statement. If the configuration parameter SMF_RECORDID was specified as 0 (zero), you have elected to disable SMF recording. If the configuration parameter SMF_RECORDID was specified as a non-zero value, the value is not valid for SMF user records. In this case, SMF recording is disabled.

If SMF recording is required, stop Mainframe Access, correct the parameter value and then restart Mainframe Access.

MFM0055I: DSS scan interval is n minutes

Issued during initialization as parameters are processed from the active configuration data set specified by the //XDBIN data definition statement. n is the value specified in the configuration parameter DSS_SCAN_INTERVAL.

MFM0056E: DSS scan interval is not valid, defaults to 2 minutes

Issued during initialization as parameters are processed from the active configuration data set specified by the //XDBIN data definition statement. An invalid value was specified for the configuration parameter DSS_SCAN_INTERVAL. The default value of two minutes was substituted for the invalid parameter value.

If two minutes is not an acceptable value, stop Mainframe Access, correct the parameter value and then restart Mainframe Access.

MFM0059E: BLDL for ISPI DLL module name failed

A request to execute ISPI module name was received from an HTTP client. The z/OS BLDL service was unable to locate this load module in the program library concatenation specified by the //DLL data definition statement.

Check that the load module name is correct and that all required program libraries are available.

MFM0060E: LOAD for ISPI DLL module name failed rc=n1 reason=n2

A request to execute ISPI module name was received from an HTTP client. The z/OS LOAD service reported a failure when reading the load module from the program library concatenation specified by the //DLL data definition statement. Return code n1 is the z/OS system completion code that would normally be reported as an abend failure by the z/OS LOAD service and n2 is the additional reason code associated with the abend code. Both values are given as hexadecimal numbers.

Refer to the z/OS system codes manual for your level of z/OS to interpret the return code/reason code pair and take appropriate corrective action.

MFM0061E: ISPI DLL module name unavailable due to rc=n1 reason=n2

A request to execute ISPI module name was received from an HTTP client. This ISPI module has been logically disabled by Mainframe Access due to a previous error condition associated with the module. The previous error may have been an z/OS LOAD service failure or a module execution failure. Return code n1 is the z/OS completion code that was reported for the original failure and n2 is the additional specific reason code associated with the completion code. Both values are given as hexadecimal numbers.

If the completion code value is of the form 00xxx000, xxx is an z/OS system completion code and you should refer to the z/OS system codes manual for your level of z/OS to interpret the return code/reason code pair and take appropriate corrective action. If the completion code value is of the form 00000xxx, the xxx value is a hexadecimal user abend code. User abend codes are normally documented as decimal values and you should convert the xxx hexadecimal value to decimal, if necessary. Refer to the program documentation for the meaning of the user abend code.

MFM0062E: Initialization failed (by name - explanation)

During initialization processing a condition was encountered that would prevent proper execution of Mainframe Access. For example, Mainframe Access' listening process for client connections was unable to allocate and/or open a socket for TCP_PORT. The component that detected the condition has initiated shutdown processing. The name identifies the task that detected the condition and explanation provides a concise statement of the problem.

Examine associated error messages in the system log, joblog and XDBOUT data set to determine the cause of the initialization failure. In most cases, the related error messages can be found just before this message in the XDBLOG data set. Correct the problem and restart Mainframe Access.

MFM0063I: MFA Direct is active

This message is issued during initialization to acknowledge that MFADIRECT=YES was specified in the parameter file.

MFM0064I: MFA Direct number of processing tasks is n

This message is issued during initialization to acknowledge that the MFADIRECT_MAXTASKS=n parameter file specification has been processed. Mainframe Access will start n z/OS tasks for Mainframe Access request processing. During execution Mainframe Access will create up to n additional tasks for Mainframe Access request processing if the transaction rate and processing load warrant.

MFM0065I: usage port number for client connections is n

This message is issued during initialization to acknowledge that the TCP_PORT parameter file specifications have been processed. The usage indicates that the "Enterprise Server" (for TCP_PORT) will be listening on port number n for client connections.

MFM0066I: Address space type is astype

This message is issued during initialization to acknowledge that the ASTYPE parameter file specification has been processed. The address space type can be "STANDARD", "CTLRGN" or "APPSERVER". The "STANDARD" address space is a stand-alone Mainframe Access server. The "CTLRGN" is a Mainframe Access server capable of starting application server regions such as the Mainframe Access Data Connect server. The "APPSERVER" address space is lightweight subset of the Mainframe Access server that is started and managed by a CTLRGN.

MFM0068I: parmname parameter specification invalid

This message is issued during initialization to indicate that the usage of parameter parmname is incorrect and this parameter was not successfully processed.

Correct the parameter specification and restart Mainframe Access.

MFM0069E: MFADirect not configured - rejecting sd=n ip=addr

Issued by the TCP/IP listener for TCP_PORT when a client connection request for Mainframe Access services is received and MFADirect services have not been configured in the initialization parameters. The client (from IP address addr on socket n) is disconnected.

Check that MFADirect services are enabled by the MFADIRECT and MFADIRECT_MAXTASKS initialization parameter settings. Restart Mainframe Access if parameter settings are changed.

MFM0070E: MFA Data Connect not configured - rejecting sd=n ip=addr

Issued by the TCP/IP listener for TCP_PORT when a client connection request for Mainframe Access Data Connect services is received and the Mainframe Access Data Connect server has not been configured in the initialization parameters. The client (from IP address addr on socket n) is disconnected.

Check that the Mainframe Access Data Connect server is enabled by the Mainframe Access FEATURE, MFALINK_MAXTASKS and ASTYPE initialization parameter settings. Restart Mainframe Access if parameter settings are changed.

MFM0071E: process access list check condition client ipaddr

This message may be issued by the TCP/IP port listeners when access list checking is active. If process is XDBTCPM, this is a connection attempt through the TCP_PORT for Micro Focus clients. Each client's IP address (ipaddr) is checked against the PERMIT and REJECT specifications in the access list. If the condition reported is "rejected", the client IP address was found to match a reject specification in the access list. In this case the client's connection request is immediately rejected. If the condition reported is "warning for", no matching reject or accept specification was found in the access list. In this case the client connection is accepted. You may wish to add an access list specification for this client or an appropriate range of similar client IP addresses.

MFM0072E: Shutdown starting due to failure (in taskname)

This message is issued when one of the Mainframe Access tasks encounters a software failure and ESTAEX processing is unable to fully recover and guarantee the integrity of subsequent processing in the address space. In this case, the ESTAEX recovery routine processing will start an automatic shutdown of Mainframe Access.

Examine the XDBOUT data set, joblog and system log for associated error messages. This may identify a problem that requires you to take a corrective action. Restart Mainframe Access and report the incident to Product Support.

MFM0074E: The following parameter statement is rejected (line n)

This message is issued during startup when an invalid parameter is found in the Mainframe Access configuration parameter file. The statement containing the invalid parameter is displayed in the message line that follows.

Mainframe Access Server completes processing of the parameter file and then shuts down due to the parameter error. Correct the invalid parameter and restart Mainframe Access Server.

MFM0077E: CG production log (ddname) open failed, errno=n _msgno=m

This message is issued during startup when the data set specified by Mainframe Access configuration parameter CGMQOTMA LOGDD cannot be OPENed.

MFM0079I: CG production log closed

This message is issued during shutdown to confirm that the data set specified by the Mainframe Access configuration parameter CGMQOTMA LOGDD has been successfully closed.

MFM0080I: MQ message queue configuration information
MFM0083I: Cross-memory initialization starting (dac=address)

This message is issued during startup when dependent address spaces are configured. Mainframe Access is preparing to create the z/OS cross-memory resources that allow Mainframe Access address spaces to communicate using Program Call. The control region is first to initialize and it establishes the cross-memory environment that allows dependent regions to call back into the control region. As dependent regions initialize (either at startup or on-demand) each dependent creates a cross-memory environment that allows the control region to call into the dependent region. This creates a bi-directional calling mechanism between the control region and each dependent region. The DAC is the primary control table for dependent address space services.

MFM0084I: Cross-memory initialization complete

This message is issued during startup when Mainframe Access has completed the setup of z/OS cross-memory resources that allow Mainframe Access address spaces to communicate using Program Call.

MFM0085I: > Start_Program sent to [rcvd from] stcname (seq=n grp=cccc pgm=cccccccc uid=cccccccc)

This message is issued when Program Call is used to pass a Start Program request to a dependent address space. The control region issues the "sent" form of the message and the dependent region issues the "rcvd" form of the message. seq= is the request sequence number used to correlate the cross-memory activity grp= is the ASGROUP name for the dependent region pgm= is the name of the program to be called uid= is the user id that will provide the program execution security environment

MFM0086I: > Program_Complete sent to [rcvd from] stcname (seq=n ServerRC=n ProgramRC=xxxxxxxx)

This message is issued when Program Call is used to pass a Program Complete indication to the control region. The Program Complete indication returns the result of a Program Call request that was passed to the dependent region. seq= is the request sequence number used to correlate the cross-memory activity ServerRC= is the Mainframe Access return code 0 = the requested program was called and executed succesfully (ProgramRC contains the return code) 1 = the requested program abended (ProgramRC contains the ABEND code) 2 = the dependent region could not load the requested program module 3 = the dependent region Mainframe Access load and call service failed 4 = the call request was not successfully passed to a dependent processing region 5 = the user credentials (userid and password) were invalid ProgramRC= is the return code value from the called program (if the ServerRC is zero)

MFM0087I: Cross-memory environment created

This message is issued during startup to confirm that the z/OS cross-memory Program Call infrastructure was successfully created in this address space.

MFM0088I: Asparm extracted (length=n)
This message is issued during startup of a dependent region to confirm that information needed to establish cross-memory communication was successfully passed from the control region to this dependent region. The asparm data is displayed in dump format following this message.
MFM0089E: Cross-memory start failed (Da_Start rc=n rs=xxxxxxxx)

This message is issued during startup if Mainframe Access is unable to create the z/OS cross-memory Program Call infrastructure.

Mainframe Access ABENDs with code U3100. Contact product support if you cannot resolve the reason for the initialization failure by examining related messages, etc.

MFM0090I: Waiting for server task to initialize

This message is issued during startup when the dependent region has received a request and the required processing task has not yet complete initialization.

This message is issued repeatedly (every second) until the server task completes initialization and is ready to accept the request.

MFM0091I: < Appserver_Started received from stcname (dab=xxxxxxxx)

This message is issued by the control region when a started dependent region has completed its cross-memory initialization and issued a confirming Program Call back to the control region. The dependent's call provides the cross-memory information that the control region needs to Program Call into the dependent region.

MFM0092I: Appserver stcname connected (dab=xxxxxxxx)

This message is issued by the control region when a started dependent region has been successfully contacted by the control region using the dependent's cross-memory Program Call information.

MFM0093E: Appserver stcname connection failed (Da_Conn rc=n rs=xxxxxxxx)

This message is issued by the control region when a started dependent region could not be contacted by the control region using the dependent's cross-memory Program Call information.

Contact product support if this problem persists.

MFM0094I: < Ctlrgn_Acknowledgement received from stcname

This message is issued by the dependent region when the control region contacts the dependent by using the cross-memory Program Call information provided by the dependent.

MFM0095I: < Start_Shutdown received from stcname

This message is issued by the dependent region when the control region uses Program Call to start shutdown processing in the dependent region.

MFM0096I: Cross-memory cleanup complete

This message is issued during shutdown to confirm that all of the z/OS cross-memory resources allocated by this address space have been successfully released.

MFM0097E: Cross-memory cleanup failed (DA_Stop rc=n rs=xxxxxxxx)

This message is issued during shutdown to report that some z/OS cross-memory resources allocated by this address space were not successfully released.

Contact product support if this problem persists.

MFM0098I: Appserver stcname is being shutdown (dab=xxxxxxxx)

This message is issued during shutdown by the control region when an active dependent region is selected to receive a Start_Shutdown Program Call. After the call the PC linkage for the dependent is removed from the control region.

This message is also issued when a dependent region is being shut down in response to a request processing ABEND in that region. When a processing ABEND occurs the control region will shut down the associated dependent region because that address space is considered unstable. For example, storage contents may be corrupted, excessive storage allocations may be accumulating, etc. A new instance of a dependent region will be automatically started when one is needed for subsequent request processing.

MFM0099I: Appserver stcname disconnected (dab=xxxxxxxx)

This message is issued during shutdown by the control region to confirm that the named dependent region has received the Start_Shutdown Program Call and its PC linkage has been removed from the control region.

This message is also issued to confirm the shutdown of an dependent region that has become unstable due to a previous processing ABEND.

MFM0100E: Appserver stcname disconnect failed (Da_Ashut rc=n rs=xxxxxxxx)

This message is issued during shutdown by the control region when the cross-memory linkage to the named dependent region cannot be successfully removed.

Contact product support if this problem persists.

MFM0101I: groupname address space group successfully created (dag=xxxxxxxx)

This message is issued during startup by the control region when the definition for an address space group has been successfully processed. This message confirms that the control structures for managing the group's address spaces have been successfully created. Message MFM0102I follows and displays the parameter values for the group. Address space group definitions are read from the Mainframe Access SERVERS file during initialization.

This message does not confirm that all values in the address space group definition are valid and usable. For example, the JCL procedure name in the definition may not exist in the proclib or the JCL procedure may have syntactical errors that will prevent it from starting.

MFM0102I: groupname - Proc(name) STCprefix(cccc) GroupID(n) Min(n) Max(n) Server(name)

This message is issued during startup by the control region and follows message MFM0101I for a successful address space group creation. This message displays the parameter values from the SERVERS definition for the group.

MFM0103I: groupname is the default address space group

This message is issued during startup by the control region when an address space group definition with GroupID=1 is processed. GroupID=1 specifies that this is the definition for a default group that will be selected if the group name or group id in a request cannot be found in an active address space group definition.

MFM0104I: No default address space group has been defined

This message is issued during startup by the control region when all address space group definitions have been processed and no default group was defined. GroupID=1 is used in a group definition to indicate the default group. There is no requirement to define a default group and system operation can proceed normally without a default group definition. Processing requests that do not specify a valid active group name or group id will be rejected.

MFM0105I: Address space stcname started for group groupname (dab=xxxxxxxx)

This message is issued by the control region when a new dependent address space is started. The stcname is the started task name assigned to the job. The groupname identifies the address space group for which this address space was started.

MFM0106E: Address space for groupname could not be started (Da_Ascre rc=n rs=xxxxxxxx)

This message is issued by the control region when a new dependent address space cannot be started. The return code and reason code from the address space creation routine are reported in the message.

The most common reason, indicated by rc=5, indicates that the maximum number of address spaces defined for the group has been reached. When rc=5 is reported, the request that initiated the address space creation must be queued to wait for one of the existing address spaces to become available.

If rc=5 is frequently reported for your system you should increase the ASMAXIMUM value for the address space group by 1. This allows an additional address space to be started and reduces the queueing delays for client requests. Contact product support if the problem persists.

MFM0107E: Definition failed for group groupname (Da_Mkgrp rc=n rs=xxxxxxxx)

This message is issued during startup by the control region when the control structures for an address space group definition cannot be successfully created.

Mainframe Access ABENDs with code U3100. Contact product support if you cannot resolve the reason for the initialization failure by examining related messages, etc.

MFM0108I: > Start_Tran sent[rcvd] to groupname (seq=n pri=n len=n1+n2 grp=cccc src=n.n.n.n)

This message is issued when Program Call is used to pass a Start Transaction request to a dependent address space. The control region issues the "sent" form of the message and the dependent region issues the "rcvd" form of the message. seq= is the request sequence number used to correlate the cross-memory activity pri= is the priority assigned to the transaction by the originator len= shows the header length (n1) and the content length (n2) grp= is the ASGROUP name for the dependent region src= is the IP address of the originator

MFM0109I: > Tran_Complete sent to [rcvd from] groupname (seq=n ServerRC=n ProgramRC=xxxxxxxx)

This message is issued when Program Call is used to pass a Transaction Complete indication to the control region. The Transaction Complete indication returns the result of a Start Transaction request that was passed to the dependent region. seq= is the request sequence number used to correlate the cross-memory activity

ServerRC is the Mainframe Access return code 0 -> the requested transaction was called and executed succesfully (ProgramRC contains the transaction return code) 1 -> the requested transaction abended (ProgramRC contains the ABEND code) 2 -> the client socket connection could not be obtained by the dependent region

ProgramRC is the return code value from the called transaction program (if the ServerRC is zero)

MFM0110I: Request queued for group groupname (qcount=n dapc=xxxxxxxx rc=n rs=xxxxxxxx)

This message is issued when a request (Start Program or Start Transaction) is received and no dependent address space is immediately available to process the request. The request is queued to the address space group to wait for an available dependent address space. If the maximum number of address spaces for the group have not been started, a new dependent region will be started to process this request. qcount= is the current number of requests waiting in the queue for this address space group dapc= is the address of the control structure that represents the unit of work rc= and rs= are the return and reason code values from the Da_Qwork service .

If this message occurs frequently, your system may perform better if you update the servers definition file for the indicated group. Increasing the ASMAXIMUM value of the group by 1 will provide an additional address space for processing client requests. This should reduce the frequency of request queueing which should result in improved response time for requests that would otherwise be queued.

MFM0111I: SAF logon for userid (sd=n (xxxxxxxx) rc=n type=n aaausr=xxxxxxxx acee=xxxxxxxx)

This message is issued when a user at a Mainframe Access client successfully authenticates by providing a userid and password that are accepted by the z/OS SAF authentication routines. Security resources, including a z/OS SAF ACEE control block, are obtained to create a security environment for this user.

MFM0112I: SAF logoff for userid (sd=n (xxxxxxxx) rc=n type=n)

This message is issued when a previously authenticated user at a Mainframe Access client changes user ids or disconnects from the server. This message confirms that the z/OS SAF ACEE and related security resources have been released.

MFM0113E: SAF error for userid (sd=n (xxxxxxxx) SafRC=n RacfRC=n RacfRS=n

This message is issued when the userid and password submitted by a Mainframe Access client are rejected by z/OS SAF authentication routines. The specific SAF and RACF return and reason codes are reported in the message. The SAF and RACF return and reason code definitions are summarized elsewhere in this seciton.

MFM0114E: Timeout for sd=n n.n.n.n at mm/dd/yy hh:mm:ss, last time: mm/dd/yy hh:mm:ss

This message is issued when a Mainframe Access client is idle for the number of minutes specified by the TIME OUT FOR CONNECTION parameter. The idle client is disconnected and associated resources are released. sd= is the socket number of the client connection n.n.n.n is the IP address of the client mm/dd/yy hh:mm:ss is the date and time when the time out occurred The "last time" is the date and time when the last client TCP/IP activity occurred.

MFM0115E: Access list I/O task initialization has failed

This message is issued during initialization if the access list file (DDNAME XDBACC) is not usable.

Disregard this error message for dependent regions. Dependent regions do not use an access list data set. If the error message is for the control region, examine related Mainframe Access and system message to determine the cause of the error. Contact product support if the problem persists.

MFM0116E: Access list DDname is missing

This message is issued during initialization if a data definition statement for DDNAME XDBACC is not found in the started task JCL.

Disregard this error message for dependent regions. Dependent regions do not use an access list data set. If the error message is for the control region, correct the started task JCL for the Mainframe Access control region and restart Mainframe Access Server. Contact product support if the problem persists.

MFM0117I: Mainframe Access ParmBlock is located at xxxxxxxx

This message is issued during initialization to display the address of the Mainframe Access Server primary control table, the ParmBlock.

MFM0118I: type [parameter definition statement]

This message is issued during initialization to display the active parameter definitions when LIST PARMS=YES is specified in the Mainframe Access startup parameters. All statements from the XDBIN parameter file (type "Parms") and the SERVERS definition file (type "Srvrs") are echoed to the XDBOUT sysout data set.

MFM0119I: Mainframe Access jobname is cccccccc

This message is issued during initialization to display the jobname assigned to this Mainframe Access address space.

MFM0120E: Servers definition for MCOID=mcoid not found sd=n (xxxxxxxx)

This message indicates that an error has occurred while Mainframe Access was processing the initial client request to bind a target CICS region to the current socket connection. The mcoid contained in the client request did not match any of the defined CICS servers and no default CICS server was defined.

Verify that the MCOID is specified correctly in the client configuration. Also verify that the Mainframe Access Server definition for that target CICS system is correct. The "Connect id" in the CICS Resource Definition should match the MCOID in the Mainframe Access Server definition. You may also create a default CICS server definition that is to be used when the client-specified MCOID does not exist. If the definitions are correct and this problem persists, contact Micro Focus Product Support for assistance

MFM0121E: MFA startup error: no DSS environment

When a transaction arrives at an Endevor Dependant Region, MFA will attempt to validate that Global Storage has been assigned for Endevor use. This messages indicates that MFA initialization has failed, and no global work areas have been pre-assigned for Endevor.

MFM0122E: Endevor setup error: No MSGLOG established

When a transaction arrives at an Endevor Dependant Region, MFA will attempt to validate that an Endevor transaction message log has been successfully allocated to this job. This is either dynamically created as jobname.CR_jobname.MFA.ENDEVOR.MSGLOG or pre-defined by the site within the DR started task JCL:

  //ENDVMSG  DD DISP=NEW,DSN=&&MSGLOG,UNIT=VIO,
//            DCB=(RECFM=FBA,LRECL=133,BLKSIZE=13300),
  //            SPACE=(13300,(10,10))

An Endevor transaction cannot be processed without a MSGLOG file.

MFM0123E: Endevor version mismatch between CR and DR

When a transaction arrives at an Endevor Dependant Region, MFA will attempt to validate that the same Endevor API version was used in both address spaces. This is necessary because the Endevor API is not downward compatible. The transaction is aborted if the version does not match. The STEPLIB concatenation must specify the same Endevor load library version in both address spaces.

MFM0124E: No Endevor API modules found

When a transaction arrives at an Endevor Dependant Region, MFA will attempt to load the module ENA$NDVR. This the entry point of the Endevor API. The transaction is aborted if the Endevor API cannot be located.

MFM0125E: name-address Task shutdown forced

Issued during shutdown when one of the Mainframe Access subtasks does end properly. name identifies the type of subtask and address is the address of Mainframe Access' task control block for the process.

This message is normal when the associated task has had a processing failure prior to shutdown. Contact product support if this message appears frequently.

MFM0126E: Tasks (n) forced during shutdown forced

Issued during shutdown when one or more of the Mainframe Access subtasks does not end properly (see message MFM0125E).

This message is normal when the associated tasks have had processing failures prior to shutdown. Contact product support if this message appears frequently.

MFM0128I MCG subtask MCGEXEC cc xxxxxxxx started for XDBMFADM cc xxxxxxxx

This is a normal operational message to log the fact that a new subtask was started for Mainframe Call Generator program execution.

MFM0128E MCG Non-zero return from IGZERRE set call; rc=ddd

The IBM IGZERRE module was called to establish a COBOL run time environment but has indicated there is a problem by returning with a non-zero return code. See the section IGZERRE Entry Conditions and Return Codes in the appendix Mainframe Call Generator for information on the return code values.

MFM0128E MCG Module IGZERRE is not available for set call

This message indicates that the IBM IGZERRE module was not loaded during startup and could therefore not be called to establish a COBOL run time environment.

MFM0128E MCG Non-zero return from IGZERRE reset call; rc=ddd

The IBM IGZERRE module was called to terminate a COBOL runtime environment during Mainframe Call Generator cleanup but has indicated there is a problem by returning with a non-zero return code. See the section IGZERRE Entry Conditions and Return Codes in the appendix Mainframe Call Generator for information on the return code values.

MFM0128E MCG No IGZERRE COBOL environment found for reset

The Mainframe Call Generator cleanup service found that no COBOL environment was previously established for the Mainframe Call Generator session that is ending.

MFM0129E MCG Unable to execute user program cccccccc

An execute request could not be completed for the named program. The preceding error messages will identify the exact cause.

MFM0129E MCG Unable to find or load user program cccccccc

The z/OS BLDL or LOAD operation for the named program failed. The preceding error messages will identify the exact cause.

MFM0129E MCG Request message sequence error

An unexpected Mainframe Call Generator request message was received from the client. The Mainframe Call Generator request is not appropriate for the current state of the remote execution operation. Start the Mainframe Access Server trace facility and recreate the problem to create a log of messages showing the sequence of messages being exchanged.

MFM0129E MCG Request message not recognized

An unexpected request message was received from the client. The request message could not be identified as a Mainframe Call Generator request. Start the Mainframe Access Server trace facility and recreate the problem to log the erroneous message.

MFM0130E MCG cccccccc ABENDed, System=Sxxxx Reason=xxxxxxxx User=Udddd

This message is issued after the Mainframe Call Generator ESTAE extension has trapped and recovered from an ABEND condition. The message provides the system (hexadecimal) or user (decimal) ABEND code. System reason codes are also logged for system ABENDs. If a SYSUDUMP (or SYSMDUMP) DD statement is available to the server, a dump is recorded for the ABEND.

MFM0130E MCG unable to call cccccccc, iSvcRC=dddd iSvcRS=dddd

This message is issued when server preparation for the Mainframe Call Generator call operation encounters an internal logic error. The MD_MCGEXEC_RUN service was called to execute the user program but this service ended with an error indicated by the return code and reason code values. The preceding error messages identify the exact cause.

MFM0130E MCG cleanup failed, iSvcRC=dddd iSvcRS=dddd

This message is issued if the MD_MCGEXEC_CLEANUP service encounters an internal logic error. The preceding error messages identify the exact cause.

MFM0131E Task cccccccc xxxxxxxx TCB xxxxxxxx terminated Udddd; callrtm rc=ddd

This message is issued when a subtask is forcibly terminated by Mainframe Access Server. The Udddd user ABEND code will be U201 for forced terminations of a MCGEXEC subtask. This could occur when the end user logs off or terminates the client while a Mainframe Call Generator session is active.

Parent topic: Mainframe Access Server Messages


Data Set Services Messages

MFMDS001I DSS Server Ready

Mainframe Access has successfully initialized the DSS component. Any pre-allocated item libraries are now ready for use.

MFMDS002I DSS Initialization failed

Mainframe Access failed to initialize the DSS component. The services normally provided by DSS are therefore not available.

MFMDS003I Cell pool build failed

The DSS component was unable to acquire enough virtual memory to build a pool of reusable resources.

Adjust the configuration or memory allocation for the Mainframe Access started task.

MFMDS004I Public File non-VSAM

The DSS component was unable to initialize a shared public file because the file specified was not a VSAM key-sequenced data set. DSS discards the request and continues processing. All item libraries are shared public files.

Ensure that all item libraries are created as VSAM key-sequenced data sets.

MFMDS005I DSS Server shutdown

The DSS server has been successfully shut down as part of the Mainframe Access shutdown procedure.

MFMDS006I DSS Server unidentified request

The DSS server detected an invalid request. DSS discards the request and continues processing.

If you see this message contact our Product Support.

MFMDS008I Online ITEM LIBRARY=data-set-name

The item library named is now online and available.

MFMDS009I Offline ITEM LIBRARY=data-set-name

The item library named has been taken offline and is no longer available.

Adjust the configuration or memory allocation for the Mainframe Access started task.

Ensure that all item libraries are created as VSAM key-sequenced data sets.

If you see this message contact our Product Support.

MFMDS010I DAIR reas/info DSN=data-set-name

DSS encountered a dynamic allocation error while attempting to allocate the specified data set. Here are some possible reason and information codes:

Reason | Info | Description
02xx | Environmental errors: memory or authorization
0352 | 0002 | Invalid data set name
0003 | Invalid member name
0004 | Invalid disposition
1708 | 0002 | Unable to locate data set name in catalog

All reason codes and information codes are in hexadecimal notation. For a full list of errors and further information on z/OS dynamic allocation errors, see Chapter 26 of the IBM manual MVS Authorized Assembler Services Guide.

MFMDS011I TIOT ENQ INTERFERENCE

A dynamic allocation request has been aborted because another system service request within this task has already locked access to the TIOT (Task Input/Output Table). The request will be re-tried after a 50 millisecond delay. For further information on OS/390 Dynamic Allocation errors, refer to Chapter 26 of the IBM publication (GC27-1763) MVS Authorized System Services Guide.

MFMDS012I M=member ENQ FAILURE RC=nnn

A member of a PDS was to be locked for exclusive access by this operation. However, the PDS member could not be locked at this time due to competion from another user. This request has already been retried several times over a three second period, and now the transaction is being aborted due to BLOCKED status. For further information on OS/390 ENQ errors, refer to the IBM publication MVS Assembler Services Reference (GC28-1910).

RC | Description ENQ RET=USE
04 | Resource not available
08 | Task already has control of this resource
12 | Task has previously failed to acquire this resource
MFMDS013E OPEN FAILED FOR SNAP | READER | SYSOUT

A transient file was not opened properly for subsequent use by MFA resource cleanup (SNAP) or job submission (READER) or logging (SYSOUT). The request is aborted. Additional IBM messages may have been displayed on the SYSLOG to explain the nature of the failure. The MFA Direct server continues to run with degraded services.

MFMDS020E Invalid z/OS file format

The file named in the associated message MFMDS031 has a file format that is not currently supported by MFA. This includes such formats as ISAM, HFS files, direct-access keyed files, and various spanned record formats.

MFMDS021E LRECL too high

DSS detected an attempt to write a logical record which exceeded the maximum logical record size for the file named in the associated message MFMDS031.

MFMDS022E Invalid file handle

DSS detected an invalid parameter list passed by a calling program.

If you see this message contact our Product Support.

MFMDS024E Invalid file name

DSS detected an attempt to create an invalid filename.

If you see this message contact our Product Support.

MFMDS026E LRECL EXCEEDS DEFINITION FOR DSN=dsname

During an update operation, a logical record was too large to be written to the selected file. The operation was aborted.

MFMDS029E RECALL FAILURE=nnnnn FOR DSN=dsname

An internal error occurred during an attempt to recall a file from IBM's HSM (Hierarchical Storage Manager). See the product documentation DFSMShsm Managing Your Own Data (SC35-0420) for details.

RC | Description
100 | DFSMShsm not available
400 | Invalid request
402 | Dataset not found
403 | Invalid dataset name
806 | Service module not found
MFMDS030E STOW error RC=nn Reason=nnnn M=member

DSS encountered an error while writing to the PDS directory for the file named in the associated message MFMDS031. The first eight characters of the member name are displayed. Here are some possible return code (RC) and reason values:

RC | Reason | Description
4 | 0 | Member name specified already exists
8 | 0 | Member name specified could not be found
12 | 0 | No space remains in the directory
16 | 01 | Permanent physical error
02 | Unable to add EOF marker to directory
04 | Unable to flush system buffers
3383 | SD37 failure: no secondary space available
3639 | SE37 failure: no secondary space available

For a full list of return codes and reasons, see the IBM manual Macro Instructions f

MFMDS031I DSN=data-set-name

This information message may accompany other system messages to indicate which data set is affected. The data set name appears as a string of up to 44 characters.

MFMDS032E FIND error RC=nn Reason=nnnM=member

DSS encountered an error while locating a member in the PDS directory for the file named in the associated message MFMDS031. The first eight characters of the member name are displayed. Here are some possible return code (RC) and reason values:

RC | Reason | Description
4 | 0 | Member name specified could not be found
4 | Insufficient RACF authority for this request
8 | Share options not granted on this PDSE
12 | This PDSE already open for output on another member
8 | 0 | Permanent physical error
4 | Insufficient virtual storage available
8 | Invalid DEB (data extent block) or data set owned by another task
12 | Physical error on buffer flush
16 | Invalid DCB
MFMDS033E BLDL error RC=nnReason=nnn M=member

DSS encountered an error while building directory information from the PDS directory for the file named in the associated message MFMDS031. The first eight characters of the member name are displayed. Here are some possible return code (RC) and reason values:

RC | Reason | Description
4 | 8 | Member name specified could not be found
8 | 0 | Permanent physical error
4 | Insufficient virtual storage available
8 | 8 Invalid DEB (data extent block) or data set owned by another task

For a full list of return codes and reasons, see the IBM manual Macro Instructions for Data Sets.

MFMDS034E Directory error RC=nn Reason=nnnn

DSS encountered an error while trying to identify the PDS member for the file named in the associated message MFMDS031. Here are some possible return code (RC) and reason values:

RC | Reason | Description
8 | 1012 | No members found in directory
12 | 1041 | Invalid parameter list
1054 | Invalid DEB (data extent block)
1057 | PDS is not open
1058 | Invalid DCB

For a full list of return codes and reasons, see the topic DESERV (Directory Entry Services) in the IBM manual Macro Instructions for Data Sets.

MFMDS035E QSAM abend Sxxx-yy

DSS has detected a QSAM failure and has directed QSAM to ignore the failure. The failure occurred while DSS was processing the file named in the associated message MFMDS031. Sxxx is the abend or system completion code and yy is the reason code. These codes are presented in hexadecimal format. Possible failures include:

Abend | Reason | Description
C37 | 4 | Invalid extents found on end-of-volume
D37 | 4 | No secondary space specified on this file, and the primary space has been entirely used. Reallocate the file to allow secondary extents or a larger primary extent.
E37 | 4 | No secondary space was available on this volume, or the number of extents has already reached 16 for this file. Reallocate the file to use larger secondary extents or move the file to a different volume where space is available.

For a full list of abend codes and reasons, see the IBM manual MVS System Codes.

MFMDS040E VSAM error DD=ddname RC=nn FB=nnn REQ=verb
DSS has detected a VSAM error probably associated with an input/output operation on an item library. Possible values for verb include:
Verb | Description
GET | Read a record
PUT | Write a record
CHECK | Verify completion of an event
POINT | Position to a specific location
ENDREQ | Cancel an operation
ERASE | Erase a record

Common return code (RC) values and feedback code (FB) values include:

RC | FB | Description
8 | 8 | Attempt to store a duplicate key
12 | Conflicting options specified violate stored sequence
16 | Record not found
20 | Physical locking conflict
24 | Volume not available
28 | Insufficient space on volume to extend the
32 | Invalid relative byte address specified
36 | Key range specified in definition excludes this key
40 | Insufficient virtual storage in the Mainframe Access address space
48 | Conflicting options on VSAM request
64 | No virtual storage to handle this level of concurrency
68 | File not open for type of processing requested
72 | Keyed request made to an ESDS
88 | Invalid switch to sequential processing without positioning
92 | Invalid replace or erase without key
96 | Attempt to modify a key on update
104 | Conflicting RPL options
108 | Invalid record length specified
112 | Invalid key length specified
4 | Read error on data component of file
8 | Read error on index component of file
16 | Write error on data component of file
20 | Write error on index component of file

For a full list of return codes and reason codes see the IBM publication DFSMS/MVS Macro Instructions for Data Sets.

MFMDS041E VSAM open error DD-ddname RC=nnFB=nnn

DSS has detected an error while attempting to open a VSAM data set. This message is accompanied by the z/OS system message IEC161I to describe the problem further. Common return code (RC) values and feedback code (FB) values include:

RC | FB | Description
4 | 116 | Warning: file was not closed properly after previous use and has not been recovered using an internal VSAM verify
118 | Warning: file was not closed properly after previous use but has been recovered using an internal VSAM verify
8 | 128 | No DD statement was found for this file
136 | Not enough virtual storage to complete the open processing
144 | I/O error while reading the catalog
152 | RACF denied open access
160 | Inconsistent open options specified
168 | File already open by another user

For a full list of return codes and reason codes see the IBM publication DFSMS/MVS Macro Instructions for Data Sets. VSAM system messages are documented in the IBM manual z/OS System Messages Volume 4.

MFMDS050E DSS services not available

An attempt has been made to use DSS; however, it is not currently available. This may be due to a failure during initialization or configuration, or it may have been terminated during system shutdown while a transaction is still running.

Review the z/OS system log and the Mainframe Access job log and SYSOUT data sets for messages related to the failure. If you need further assistance contact our Product Support.

MFMDS052I CA/PANVALET READY

MFA has initialized full access to CA/Panvalet services.

MFMDS053I CA/ENDEVOR API REL=Brrvvv ESI=a UID=a

MFA has initialized full access to CA/Endevor API services using the release and version specified, and noting whether the External Security (ESI) or Alternate User ID (UID) features are active.

MFMDS054I Librarian Exit Table active

MFA has created a memory table to describe the selected exits to be specified during batch updates against the corresponding Librarian master file.

MFMDS055I MCG/RPC feature (in)active

Indicates whether the MCGLIB DD card was specified as the LOAD library for remote calls as used by the Mainframe Call Generator (MCG) interface.

MFMDS056I ChangeMan DD=CMNxxxx Open failure

Access to site overrides specified for DD=CMNLIB$ and DD=CMNOPTS (to define default build procedures and site options repectively) failed during MFA startup.

MFMDS057I CA/PANVALET member security exit loaded

The user exit MFAPVXIT was found and loaded to provide member-level security for Import, Export, and Directory access calls agains Panvalet master files.

MFMDS058I Librarian ELIPSGEN not found

This site configuration file is used to validate library types and language names for establishing Librarian run-time parameters. Without this information, new objects will default to TYPE=COB.

Parent topic: Mainframe Access Server Messages


MFA Direct Messages

MFA0101I LOGON USER=userid TIME=hhmm DAY=nnn ID=nnnnnnn VER=nn

This information message indicates the time and date that a user session was established with the MFA Direct component. The time is specified using 24-hour clock notation, and the day is the day of the year. The ID represents the relative session number so as to differentiate when the same user has logged on multiple times.

MFA0102I LOGOFF USER=userid ID=nnnnnnn

A user has logged off the system. This message is added to both the MFALOG and the SYSLOG.

MFA0103I AUTH FAIL USER=userid RC=rc RACF=rr/ss

A user logon failed to pass security authorization. The reason codes are tabulated below. MFA also inserts a logon failure message into the AUDIT log. Similarly, an IBM system diagnostic (RACF) may be added to the SYSLOG

RC | RACF | Description
04 | 04/00 | No decision made
04/04 | No RACF profile found
04/08 | Request failed
08 | 08/00 | Not authorized to logon
MFA0105I {AUTH or FAIL} USER=userid INTENT=action AM=method DSN=dsname
where:
action | is READ, WRITE or ALTER
method | is QSAM, BPAM, VSAM, LIBR, PANV, IMS or DB2
dsname | is the file being accessed

The results of a user access attempt are logged in the MFALOG. This provides an audit trail of the individual file accesses processed by MFA Direct. The information is only accumulated for those systems configured with the parameter: MFA_SAF_HISTORY=YES

MFA0111E MFA INVALID DISPATCHING VERB

MFA Direct has been scheduled with an invalid request. The request will not be serviced. This represents an internal protocol error by MFA. Please contact Micro Focus support if the problem persists.

MFA0112E MFA MCB Environment failure

MFA Direct is unable to initialize a new thread due to an unexpected environmental error. The new thread is rejected. Please contact Micro Focus support to report the problem.

MFA0113E MFA TSA already in use

An MFA thread has been unexpectedly re-dispatched while it is still processing a prior request. The new request is rejected. Please contact Micro Focus support to report the problem.

MFA0801E JES/SAPI RC=xx REASON=yy

A request using the JES Sysout API to retrieve a held file from JES spool has failed. Return codes and reason codes are documented in the IBM publication: Using the Subsystem Inferface (SC28-1879) A partial list is provided below:

RC | Reason | Description
08 | Invalid search argument(s)
12 | Unable to process now
16 | Duplicate job name
20 | Invalid destination
32 | Logic error
32 | Conflicting arguments
36 | Invalid destination arguments
40 | Invalid job number
44 | Invalid form
96 | SAPI request header error
36 | Invalid CLASS
40 | Invalid disposition options
MFA0802E I/O ERROR ON INTERNAL READER

A request to submit a job to the JES internal reader has failed. The action is aborted. There may be an associated IBM system diagnostic on the SYSLOG indicating the nature of the failure.

MFA0803E JES SSI ERROR FUNC=xx RC=yy

A request using the JES Subsystem interface has failed. The only functions issued by MFA are FUNC=79 (SYSOUT API) or FUNC=80 (Extended Status API). Return codes and reason codes are described in the IBM publication: Using the Subsystem Interface (SC28-1879) A partial list is provided below:

RC | Description
04 | Function not supported
08 | JES not available
12 | JES does not exist
16 | Fatal error
20 | Logic error
24 | SSI not initialized
MFA0804E JES STATUS RC=xx REASON=yy

A request using the JES Extended Status API to acquire details of the next held output on JES spool has failed. Return codes and reason codes are documented in the IBM publication: Using the Subsystem Interface (SC28-1879) A partial list is provided below:

RC | Reason | Description
04 | Invalid search argument(s)
08 | Logic error
04 | Invalid destination
08 | Job ID low invalid
0C | Job ID high invalid
10 | Job ID high too low
14 | Invalid Job class
20 | Unable to access Job queue
24 | Invalid control structure
28 | Invalid length
2C | Invalid job name
30 | Invalid user name
34 | Invalid system name
MFA1034I CSI CATALOG ERROR nn RC=nnn REASON=nnn (ID) filter

An error occurred within the Catalog Search Interface as provided by IBM as part of the DF/SMS z/OS middleware. The ID represents an internal IBM software module ID, and the filter is the Catalog Search argument derived from the client input. The return codes are described in the IBM publication DF/SMS Managing Catalogs (SC26-7401), but a partial list is shown below. Most other return codes and reason codes are documented as part of IBM System Message IDC3009I and can also be found using the IBM Web Service LOOKAT.

RC | REASON | Description
100 | 04 | Access error on catalog
122 | 04 | Invalid filter key
MFA1035I CATALOG ERROR RC=nnn VOL=volid DSN=dsname

An error occurred attempting to OBTAIN a catlog record for the specified dsname on the specified volume ID. The dsname may no longer be catalogued on that volume, and MFA is unable to determine the file attributes. It is possible that the volume is simply not mounted, or is no longer in active service. This file will be ignored and processing will continue. The return codes are described in the IBM publication DFSMSdfp Advanced Services (SC26-7400)

RC | Description
04 | Volume not mounted
08 | The format-1 DSCB was not found in the VTOC of the specified volume
12 | A permanent I/O error was encountered reading the VTOC of the specified volume
16 | An invalid workarea pointer was encountered
MFA1036I CSI VSAM ERROR RC=nnn REASON=nnn DSN=dsname

An error occurred attempting to use the CSI interface to identify the VSAM attributes of the specified dataset. This file will be ignored and processing continues. The return codes are as described for message MFA1034I.

MFA1037I CSI GDGB ERROR RC=nnn REASON=nnn DSN=dsname

An error occurred attempting to use the CSI interface to identify the file attributes of the specified generation data group. This file will be ignored and processing continues. The return codes are as described for message MFA1034I.

MFA4001E CA/LIBRARIAN ERROR REQ=aaaa RC=nnn

An internal CA/Librarian error occurred while processing the FAIR API request identified as: aaaa={OPN or LOC or MOD or REC or CLS} The return codes are described in the CA licensed documentation CA/Librarian File Access Interface Routines Guide. A partial list is provided below:

REQ | RC | Description
OPN | 1 | Invalid filename or unauthorized
2 | DDname missing
8 | Invalid parameter
9 | Not enough storage to process
LOC | 1 | Required module not found
2 | Caller not authorized for request
6 | Disk access failure
7 | Format error on access
8 | Invalid parameter
9 | Not enough storage to process
MOD | 1 | No modules found
2 | Caller not authorized for request
3 | Module not archived
6 | Disk access failure
7 | Format error on access
8 | Invalid parameter
9 | Virtual storage shortfall
REC | 1 | End of module
6 | Disk access error
7 | Format error on access
8 | Invalid parameter
9 | Virtual storage shortfall
CLS | 81 | Close failed
MFA4002E OPEN FAILED ON LIBRARIAN UPDATE

The system was unable to open a temporary work file for use with the batch update utility AFOLIBR in an attempted Librarian update operation. Additional information may be available on the SYSLOG if an associated IBM internal system problem was encountered. As well, a small MFA snap dump will be issued to provide additional problem determination data. No batch update will be attempted. If you are unable to resolve the problem, open an incident with Micro Focus product support, and include the Snap Dump and the MFALOG as part of the problem description.

MFA4003E WRITE ERROR ON LIBRARIAN UPDATE

The system was unable to write to a temporary work file for use with the batch update utility AFOLIBR. Additional information may be available on the SYSLOG if an associated IBM data access error was encountered. As well, a small MFA snap dump will be issued to provide additional problem determination data. No batch update will be attempted. The probable cause here is an attempt to write a record (from the workstation) which exceeds the logical record size of the work file.

MFA5001E CA/PANVALET ERROR REQ=aaaa RC=nnn MSG=PVnnn

An internal Panvalet error occurred while processing a PAM API request identified as: aaa={OPEN or CLS or READ or SRCH} The return codes and PanValet message numbers are documented within the CA licensed documentation: CA/Panvalet Messages Guide CA/Panvalet System Management Guide An incomplete summary follows:

Message | Description
PV001 | Invalid command
PV002 | Member name invalid
PV003 | Invalid sequence number
PV004 | Excessive parameters
PV005 | Required parameter missing
PV006 | Numeric parameter too large
PV007 | Parameter exceeds 10 characters
PV008 | Unsupported language format
PV009 | Invalid parameter
PV012 | No statement found
PV023 | Name not found
PV032 | Sequence error
PV033 | Library error
PV036 | Access error: member locked
PV043 | Library storage exceeded
PV046 | Panvalet library empty
PV047 | Virtual storage shortfall
PV051 | Invalid Library file
PV066 | Function terminated due to errors
PV070 | Statement truncated
PV095 | Invalid DCB for Library
PV118 | LRECL must be 80 for this language type
PV124 | Invalid file
MFA5002E CA/PANVALET LICENSE FAILURE: access quiesced

This site is not licensed to access the PanValet API. Further attempts to access PanValet will be suspended by MFA to avoid repetitive errors. Contact PanValet support to re-establish your license keys. Re-starting MFA will resume PanValet access attempts.

MFA5003E CA/PANVALET PAN#1 error RC=nnnnn

An internal Panvalet error was encountered while processing a batch update request using the PAN#1 utility. The return codes are described within the CA licensed documentation: CA/Panvalet Messages Guide CA/Panvalet User Guide

MFA5004E I/O ERROR on PANVALET Temporary file

A QSAM error was encountered while writing a temporary file needed as a pre-requisite for the PAN#1 batch update utility. Normally, an IBM system error will appear on the SYSLOG to describe the actual reason, The probable cause is an attempt to write a logical record from the workstation which exceeds the logical record size of the host file.

MFA6001E ENDEVOR API ERROR REQ=aaaa RC=nnn/rrrr/msgid

An Endevor internal processing error occurred while processing an API request identified as: aaaa={ERET or LELM or EADD} A copy of the actual Endevor error message is inserted into the MFALOGE listing if MFA_ENDEVOR_LOGGING is active. The return code, reason code, and Endevor message numbers are described in the licensed CA/Endevor documentation: Endevor for z/OS Messages and Codes Endevor for z.OS API Guide

MFA6002E I/O ERROR ON ENDEVOR TEMPORARY FILE

A QSAM error was encountered while writing a temporary file needed as a pre-requisite for an Endevor API request. Normally, an IBM system error will appear on the SYSLOG to describe the actual reason, The probable cause is an attempt to write a logical record from the workstation which exceeds the logical record size of the temporary file.

MFA6003E SYNTAX ERROR ON ENDEVOR ENVIRONMENT STRING

An invalid environment string was encountered during an Endevor request. The transaction is aborted. Use you client software to re-specify the Endevor prompts and properties correctly.

MFA6004E ENDEVOR INTERFACE ABEND: abend-reason userid session-id

The Mainframe Access ESTAE recovery routines detected an abend while processing an Endevor transaction. The transaction is aborted. The above message appears in the MFALOG showing the diagnostic abend code and reason code.

Parent topic: Mainframe Access Server Messages


Data Connect Messages

MFA100E ESTAE ENTERED ABEND CODE Uxxx/Sxxx

Data Connect has detected an abend. The client software is notified and the dump is normally suppressed. See the MVS console log for additional imformation.

MFA101E LIMIT OF 256 PROCESSES EXCEEDED

Logic within Data Connect can manage up to 256 concurrent sessions. It is unable to retain positioning and recovery information for additional sessions.

MFA110I VTAM PROCESSOR ACTIVE USING VTAMAPPL applid

Data Connect has successfully created a VTAM connection and is available to service message traffic using APPLID=applid.

MFA111W VTAM ACB CLOSE FAILURE

Data Connect was unable to close the VTAM connection successfully. This may be a VTAM environmental problem. See the MVS console log for additional information. Shutdown processing continues without VTAM access.

MFA112I VTAM PROCESSOR HAS TERMINATED

Data Connect is no longer servicing VTAM message traffic. Shutdown processing continues normally.

MFA113E USING VTAMAPPL applid ACB OPEN ERROR X"xx"

Data Connect was unable to open the specified APPLID. Therefore, access cannot be provided to network clients. Common errors are identified as described below.

Error | Description
54 | APPLID not defined to VTAM
58 | APPLID already in use
5A | APPLID inactive to VTAM
MFA114E APPC SESSION REJECTED PRI=xxxxxxxx SEC=xxxxxxxx

Data Connect was unable to complete the logon attempt. See the VTAM APPC documentation for a description of the primary and secondary return codes provided by IBM.

MFA115E MFA DOES NOT SUPPORT 3270 DATASTREAMS

Data Connect does not support LU2 3270 data stream connections. Only APPC VTAM message traffic is supportted.

MFA201W ERROR OPENING DDNAME=VSAMCTL

A file open error was encountered for the VSAM control file. Verify that DDNAME was provided in the Data Connect started task as shown in the sample JCL as MFAS. See the z/OS console log for additional error messages.

MFA202I ERROR READING VSAMCTL FOR membername

A file read error was encountered for the indicated member name. The physical data may be corrupted. See the z/OS console log for additional error information.

MFA299E ADDRESS SPACE NOT AUTHORIZED

The Data Connect modules must reside in an authorized library. The STEPLIB concatenation probably contains at least one load library which is not APF-authorized. Please call your system programmer to authorize your libraries.

MFA301E JCL PARM INVALID OR OMITTED

The parm passed on the // EXEC PGM=MFDSTART,PARM='...' is invalid. The only keyword supported is APPLID=applid. Correct the JCL before resubmitting this job.

MFA302I ATTACHING VTAM PROCESSOR

Data Connect is now initializing APPC access for client messages as relayed through the Host Connectivity interface.

MFA303I MFA/DATACONNECT V4.00 - vers

This message identifies the Data Connect version and copyright information.

MFA310E INVALID OPERATOR REQUEST IGNORED

An invalid operator command was sent to Data Connect. The command is being ignored.

MFA311W PROCESS ALREADY RUNNING

VTAM APPC support is already active. It is not possible to re-cycle commnications while the APPLID is still active.

MFA317I jobname HAS BEEN TERMINATED

The Data Connect task has been successfully terminated.

Parent topic: Mainframe Access Server Messages


Drag and Drop Error Messages

Refer to the table below for a list of possible error messages:

Error Message | Return code | Description
MFDAS01: Mainframe access problem. | 1001 | A communication problem has been detected. Refer to the MFAERROR.LOG file for more information.
MFDAS02: Cannot import multiple files to a single file. | 1002 | An illogical request has been made, in that the user is attempting to import more than one file into a single file.
MFDAS03: Cannot export multiple files to a single file. | 1003 | An illogical request has been made, in that the user is attempting to export more than one file into a single file.
MFDAS04: Module 'MFLSC' is missing or inaccessible. | 1004 | The required module MFLSC cannot be found. This is most likely an installation problem.
MFDAS05: File had no length, or does not exist. | 1005 | The file had either a zero length, or had been deleted but the display was not refreshed.
MFDAS06: Call to module 'DFCONV' failed. Unable to convert the VSAM/QSAM file. | 1006 | A bad return code was given by the converter program. Run the dfconv program on its own to determine the error.
MFDAS07: Value is not a valid number. | 1007 | A non-numeric value was given when a numeric value was expected.
MFDAS08: For VSAM/QSAM files, extensions of PRO, DAT, or IDX are reserved. | 1008 | You cannot use a restricted extension for a file transfer.
MFDAS09: Rename to file failed. | 1009 | An error was returned when trying to rename a file.
MFDAS10: The allocation of failed with message number. | 1010 | An error message has been returned from the COBOL development environment. See the product documentation for a description of the message.
MFDAS11: The allocation of differs from the mainframe. | 1011 | The DCB information for the COBOL development environment dataset differs from that of the mainframe.
MFDAS12: One or more of the fields have not been properly entered. | 1012 | Insufficient or incorrect information has been provided in the panel.
MFDAS13: The PC file name cannot have more than 4 subdirectory levels. | 1013 | The COBOL development environment is unable to support more than 4 subdirectory levels.
MFDAS14: Mismatch between new and repeat passwords. | 1014 | The new and repeat passwords given do not match.
MFDAS15: Unable to make the directory. | 1015 | An error was returned when trying to create a directory.
MFDAS16: Unable to remove directory. | 1016 | An error was returned when trying to remove a directory.
MFDAS17: Call to module 'PCIMS' failed. Unable to convert the IMS database. | 1017 | A bad return code was given by the PCIMS program. Run the PCIMS program on its own to determine the error.
MFDAS18: A catalog search criteria must be entered. | 1018 | You must enter one or more mainframe catalog search criteria. If specifying more than one, then separate them by commas. This catalog search criteria is similar to that when using ISPF 3.4.
MFDAS19: A real workstation drive must be used. | 1019 | The drive selected for the COBOL development environment dataset does not exist on this workstation.
MFDAS22: Call to module 'SQL-Wizard' failed. Unable to convert the XDB table. | 1022 | A bad return code was given by the SQL wizard program. Run the SQL wizard program on its own to determine the error.
MFDAS23: Cannot establish connection to the mainframe server. | 1023 | Unable to connect to the mainframe server.
MFDAS24: Network communication problems with blocks of size. | 1024 | The user's network is unable to transport a data block of the size specified. This is most likely a router configuration problem. To temporarily circumvent the problem, you can specify the MFAMAXSENDLENGTH environment variable, with the value set to a size below the size in error.
MFDAS25: CCI module was not found. | 1025 | The CCI communications file is not found.
MFDAS26: Module is not a CCI module. | 1026 | The module specified is not a CCI communications file.
MFDAS27: Unable to delete file. | 1027 | An error was returned when trying to delete a file.
MFDAS28: Either recall this dataset or assign a type. | 1028 | This dataset is migrated. Either use the right-mouse context to recall it, or assign a specific type.
MFDAS29: Assign a type to this dataset. | 1029 | Unknown DSORG for this dataset. You need to use the right-mouse context to assign a specific type.
MFDAS30: The workstation dataset is connected to the mainframe | 1030 | This workstation dataset you are tying to access is redirection to a mainframe dataset.
MFDAS31: Copy of file failed. | 1031 | Unable to copy from the Windows clipboard.
MFDAS32: Paste of file failed. | 1032 | Unable to paste the file to the Windows clipboard.
MFDAS33: PCIMS is not available. Unable to convert the IMS database. | 1033 | The PCIMS.LBR routines could not be found, or a project was not open.
Parent topic: Mainframe Access Server Messages
Parent topic: Drag and Drop


Status Codes and Error Messages

This section contains a list of status codes that Mainframe Access servers can return to a client program. It also documents the anomalies in file status settings based upon the environment in which the I/O statements are executed.

Note: For additional information on MFA messages, see your Mainframe Access Administrator's Guide.
  • Status Codes Returned by the MVS Server
  • File Status Comparisons
Parent topic: Mainframe Access Messages


Status Codes Returned by the MVS Server

Table 1. File Status Codes Returned by the MVS Server
Status Code | Description
0/0 | The MVS server returns a status of 0/0 when writing a record to an indexed file which results in two or more records with identical keys. Both IBM VS COBOL II batch processing and Micro Focus COBOL return a status of 0/2 when such a condition arises.
0/5 | A file status 0/5 indicates an open operation was successful, but the file is empty. A file status of 0/5 is returned in some cases where IBM VS COBOL II returns a status of 0/0 and in other cases where IBM VS COBOL II returns a status of 3/5. See the appendix File Status Comparisons for some examples of the conditions under which this status code is returned during open processing.
4/3 | A status code of 4/3 is returned if an attempt is made to delete a VSAM record via an alternate index, if another record in that file contains the same key as the record being deleted.
4/6 | If an I/O operation is attempted which requires a previous I/O operation to have set the current record pointer, and the previous I/O operation failed, a file status of 4/6 is returned. It is also issued if the MVS server loses track of the current record position, probably due to an invalid sequence of I/O statements.
9/100 | A file status of 9/100 is returned if the MVS server receives an operation code that it does not support. This status is also returned when the server attempts to execute a command at a time when that command is invalid. In this case, the operation code received by the server was valid, but the I/O operation was invalid given the type of operation requested and the nature of the previous I/O operations executed for the file.
9/125 | A status code of 9/125 will be returned when the maximum number of concurrent Users has been exceeded.
9/242 | The requested function or component has not been licensed.
Parent topic: Status Codes and Error Messages


File Status Comparisons

This section documents the anomalies in file status settings based upon the environment in which the I/O statements are executed. Expected results, including expected anomalies (for example, the order of records returned when reading an alternate index in reverse order), are not included in this list unless they help clarify the conditions under which the anomalies were detected.

These results were compiled from a set of test programs executed in the following three environments:

  • MVS-batch using IBM VS COBOL II accessing VSAM datasets
  • OS/2 using Micro Focus COBOL accessing sequential
  • Relative and indexed files

The test programs used an extensive combination of file definitions (organization and access mode), open types (INPUT, I/O, OUTPUT, EXTEND, etc.), and I/O verbs for example READ, WRITE, REWRITE) to examine the behavior of execution environment and the results of the file status information returned to the test programs.

In the Cross Reference of File Status Setting table that follows, file status information obtained for the tests in each environment is displayed in the format 'a/b', where 'a' represents the first byte of the file status (file status 1) and 'b' represents the second byte of the file status (file status 2).

For run-time errors, the first byte displayed is '9' and the value for the second byte is the ordinal value of the file status 2 field (e.g. 9/100). When an I/O operation is invalid, a key of 'N/A' is used. When an I/O operation is valid but was not tested because of the results of an earlier I/O operations, a file status of '-/-' is used.

  • Cross Reference of File Status Setting
Parent topic: Status Codes and Error Messages


Cross Reference of File Status Setting

READ SEQUENTIAL TEST WITH EMPTY FILES

FILE ORG-ACC | I/O statements | MVS-BATCH COBOL II | OS/2 MF/COBOL | CICS server
SEQ SEQ | OPEN I/O | 3/5 | 0/5 | 0/5
 | READ NEXT | -/- | 1/0 | 1/0
SEQ SEQ | OPEN I/O REVERSED | N/A | 0/0 | 0/5
 | READ NEXT | -/- | 1/0 | 1/0
REL SEQ | OPEN I/O | 3/5 | 0/5 | 0/5
 | READ NEXT | -/- | 1/0 | 1/0
REL SEQ | OPEN I/O | 3/5 | 0/5 | 0/5
 | START RRN=20 | -/- | 2/3 | 2/3
REL SEQ | OPEN I/O | 3/5 | 0/0 | 3/5
 | START RRN=0 | -/- | 2/3 | -/-
IDX SEQ | OPEN INPUT | 0/0 | 3/5 | 0/0
 | READ NEXT | 1/0 | -/- | 1/0
IDX SEQ | OPEN I/O | 0/0 | 0/5 | 0/0
 | START KEY < VALUE | N/A | 2/3 | 2/3

When Micro Focus COBOL attempts to open a sequential dataset for I/O REVERSED processing and that dataset does not exist, a status code of 3/5 is returned. If the dataset does exist but is empty, a status code of 0/0 is returned on the open request.

WRITE SEQUENTIAL TEST WITH EMPTY FILES

FILE ORG-ACC | I/O statements | MVS-BATCH COBOL II | OS/2 MF/COBOL | CICS server
IDX SEQ | OPEN OUTPUT | 0/0 | 0/0 | 0/0
 | WRITE (RECORD W/DUPLICATE ALT KEY) | 0/2 | 0/2 | 0/0
IDX SEQ | OPEN EXTEND | 0/0 | 0/0 | 0/0
 | WRITE (RECORD W/DUPLICATE ALT KEY) | 0/2 | 0/2 | 0/0

The CICS server cannot determine if the result of this write operation would cause any alternate indexes to have two or more records with the same key value.

DELETE SEQUENTIAL TEST

FILE ORG-ACC | I/O statements | MVS-BATCH COBOL II | OS/2 MF/COBOL | CICS server
IDX SEQ | OPEN I/O | 0/0 | 0/0 | 0/0
 | START ALT KEY GTEQ LOW-VALUES | 0/0 | 0/2 | 0/0
 | DELETE | 0/0 | 0/0 | 1/0

The CICS server does not permit the deletion of a record via the alternate index if another record in the file has the same key for the alternate index. A status code of 4/3 is returned. The current record position is unaffected by the failed request.

RANDOM WRITE TEST

FILE ORG-ACC | I/O statements | MVS-BATCH COBOL II | OS/2 MF/COBOL | CICS server
IDX RAN | OPEN I/O | 0/0 | 0/0 | 0/0
 | WRITE (RECORD W/DUPLICATE ALT KEY) | 0/2 | 0/2 | 0/0

The CICS server cannot determine if the result of this write operation would cause any alternate indexes to have two or more records with the same key value.

READ SEQUENTIAL TEST WITH DATA IN FILES

FILE ORG-ACC | I/O statements | MVS-BATCH COBOL II | OS/2 MF/COBOL | CICS server
IDX SEQ | OPEN INPUT | 0/0 | 0/0 | 0/0
 | START KEY GTEQ HIGH-VALUES | 2/3 | 2/3 | 0/0
 | READ NEXT | -/- | -/- | 1/0

VSAM treats this as: 'position the current record pointer to the end of the file'; a subsequent READ PREVIOUS request would return the last record in the file.

READ DYNAMIC TEST WITH DATA IN FILES

FILE ORG-ACC | I/O statements | MVS-BATCH COBOL II | OS/2 MF/COBOL | CICS server
IDX DYN | OPEN INPUT | 0/0 | 0/0 | 0/0
 | START KEY GTEQ HIGH-VALUES | 2/3 | 2/3 | 0/0
 | READ NEXT | -/- | -/- | 1/0

VSAM treats this as: 'position the current record pointer to the end of the file'; a subsequent READ PREVIOUS request would return the last record in the file.

DELETE DYNAMIC TEST WITH DATA IN FILES

FILE ORG-ACC | I/O statements | MVS-BATCH COBOL II | OS/2 MF/COBOL | CICS server
IDX DYN | OPEN I/O | 0/0 | 0/0 | 0/0
 | START ALT KEY GTEQ LOW-VALUES | 0/0 | 0/0 | 0/0
 | READ NEXT (DUPLICATE KEY) | 0/2 | 0/2 | 0/2
 | READ NEXT (LAST OF DUPLICATE KEY) | 0/0 | 0/0 | 0/0
 | DELETE (LAST OF DUPLICATE KEY) | 0/0 | 0/0 | 4/3

The CICS server does not permit the deletion of a record via the alternate index if another record in the file has the same key for the alternate index. A status code of 4/3 is returned. The current record position is unaffected by the failed request.

Parent topic: File Status Comparisons


Using Enterprise Server with a Mainframe

The information in this section describes how to use the mainframe access functionality from within your Enterprise Server applications.

  • Drag and Drop
    The Drag and Drop utility allows you to transfer files using drag and drop methods, between the mainframe and your local environments.
  • Remote Job Step Execution
  • Compare and Synchronization Monitor
  • SourceConnect: Mapping a PC Drive to Mainframe Data
Parent topic: Working with Mainframe Files


Drag and Drop

Enterprise Developer has the following variations of the Drag and Drop functionality:

  • Using the Command Line Interface
    The Drag and Drop command line interface, in which you can perform file-related interactions with the mainframe.
  • Drag and Drop Error Messages
    Error messages relating to Drag and Drop are prefixed MFDAS.
Parent topic: Using Enterprise Server with a Mainframe


Using the Command Line Interface

The Drag and Drop command line interface, in which you can perform file-related interactions with the mainframe.

With the command line interface, you use the MFDAS command with the appropriate parameters. These options are described in the following sections.

  • Providing Your Own Security Exit to The Command Line Interface
  • Importing Data
  • Exporting Data
  • Submitting Files
  • Locating Data Sets
  • Retrieving Endevor Footprints
  • Changing Your Mainframe Password
  • Specifying Servers, Nodes and Ports
  • Displaying a Directory List
  • Using the Command Line Application Program Interface
  • MFDAS
    Use the MFDAS command line utility to perform a range of file-related interactions with the mainframe.
Parent topic: Drag and Drop


Providing Your Own Security Exit to The Command Line Interface

The command line interface, will by default, prompt you for the user ID and password to be used for the command. You can, however, provide this to the command line interface, by coding a COBOL GNT module with the name MFDASPWD. This program will be called and will be passed two linkage section items: user ID for 20 bytes and password for 20 bytes. Your exit program can then provide the user ID and password to be used, instead of prompting you for the information:

IDENTIFICATION DIVISION.
PROGRAM-ID. MFDASPWD.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 Ws1          PIC X.
LINKAGE SECTION.
01 LsUserid     PIC X(20).
01 LsPassword   PIC X(20).
PROCEDURE DIVISION USING LsUserid LsPassword.
P1.
     Move 'MFIUVE' to LsUserid
     Move 'MF081190' to LsPassword
           GOBACK.

After compiling mfdaspwd.cbl, you must place mfdaspwd.gnt into the directory .

Keywords, enclosed in square brackets, are optional. Italicized keywords are user supplied data.

Parent topic: Using the Command Line Interface


Importing Data

You can import individual members, or a collection of members defined by a filter, from the JES spool, a partitioned data set or source code control system, or you can import entire QSAM, VSAM data sets, IMS databases or DB/2 tables, with automatic data conversion to the appropriate Micro Focus format. You may optionally specify a control file containing one or more commands and allow MFDAS to run them as a batch. To do this, place the commands in a control file of any name, without the preceding MFDAS parameter, then run MFDAS with the parameter @filename, where filename is the name of the control file.

Note: You can configure user exits to perform actions after a successful import.

Text or binary transfers are possible. Use the BINARY or TEXT operand to override the default transfer type for the type. The default transfer type for PDS, Librarian, Panvalet or Endevor is TEXT. The default transfer type for QSAM is BINARY. VSAM, IMS and DB/2 cannot be overridden.

The MEMBER parameter can specify a specific mainframe member name, or can include special filter characters to allow multiple imports to occur based on the special filter characters that you specify. These special filter characters are:

  • * means any characters may follow
  • ? means any character in this position
  • + means the character in this position must be non-blank
  • - means the character in this position must be blank
  • \ means the character in this position must be non-numeric
  • / means the character in this position must be numeric

Example import commands are shown below.

JES

To import from the mainframe JES2 or JES3 spool:

MFDAS IMPORT filename FROM JES
JOB#####|filter

PDS

To import from a Partitioned data set:

MFDAS IMPORT {BINARY | TEXT} filename FROM PDS
pdsname
MEMBER {memname|filter}

Librarian

To import from a Librarian data set:

MFDAS IMPORT {BINARY | TEXT} filename FROM LIB
libname
MEMBER {memname|filter}

Panvalet

To import from a Panvalet data set:

MFDAS IMPORT {BINARY | TEXT} filename FROM PAN
panname
MEMBER {memname|filter}

Endevor

To import from an Endevor data set:

MFDAS IMPORT {BINARY | TEXT} filename FROM END
ENV 'env' SYS 'sys' SUB 'sub'
MEMBER {memname|filter}
STG 'stage'
TYPE memtype
CCID change-control-id
COMMENT user-comment
OVERRIDE SIGNOUT
LOCK=YES

QSAM

To import from a QSAM data set with automatic data conversion:

MFDAS
IMPORT {BINARY | TEXT} filename FROM QSAM
qsamname

VSAM KSDS

To import from a VSAM KSDS data set with automatic data conversion and produce a variable length workstation indexed file. If you wish to produce a fixed length indexed file, then use KSDS-FIXED instead of KSDS.

MFDAS IMPORT filename FROM KSDS
vsamksdsname

VSAM ESDS

To import from a VSAM ESDS data set with automatic data conversion and produce a variable length workstation indexed file. If you wish to produce a fixed length indexed file, then use ESDS-FIXED instead of ESDS.

MFDAS IMPORT filename FROM ESDS
vsamesdsname

VSAM RRDS

To import from a VSAM RRDS data set with automatic data conversion and produce a variable length workstation indexed file. If you wish to produce a fixed length indexed file, then use RRDS-FIXED instead of RRDS.

MFDAS IMPORT filename FROM RRDS
vsamrrdsname

IMS Database

To import from an unloaded IMS database with automatic data conversion and produce a workstation PCIMS format database. Three additional parameters are available after the mainframe IMS unloaded data setname field. These parameters are the required database name, location of segment name in the data record (relative to 1) and the location of the segment data in the data record (relative to 1). If the mainframe database has been unloaded using the Micro Focus PCIMS unload utility, then these three fields are not required, as they are automatically picked up from the mainframe unloaded data set.

MFDAS IMPORT filename FROM IMS
imsunloadedname
[databasename]
[segmentnamelocation]
[segmentdatalocation]
Note: To view the database after import, you must also point the ES_IMSLIB environment variable at the generated DBD files (dbdgen2.dat and dbdgen2f.dat), ES_IMSDAT at the actual IMS database file, and ES_IMSWRK to a location that listing and log files can be written to (although, if this variable is not set, the listing and log files are created in the current directory).

DB/2 Table

To import from an unloaded DB/2 table with automatic data conversion and produce a workstation XDB format table. Three additional parameters are required after the mainframe DB/2 unloaded data setname field. These parameters are the required location, authid, and table name. The mainframe table must have been unloaded into a sequential file using the DSNTIAUL DB/2 unload utility. The table must exist and the SQLWizard must be available on the path.

MFDAS IMPORTfilename FROM DB2
db2unloadedname location
authid tablename
  • Importing Data with Auto-catalog
Parent topic: Using the Command Line Interface


Importing Data with Auto-catalog

When importing files using the MFDAS IMPORT command line you can use the auto-catalog feature so that imported PDS, QSAM, ESDS, RRDS, and KSDS data sets are automatically added into a catalog.

When using the auto-catalog feature, a number of additional new features are available to give you more control over the import and catalog process. To use the auto-catalog feature you specify the /CATLOC=catalog-file-name argument as part of an MFDAS IMPORT command, where catalog-file-name is the catalog file into which the imported data set should be cataloged.

Example:

MFDAS IMPORT c:\mfi01.test.data.txt FROM QSAM mfi01.test.data /CATLOC=c:\proj\catalog.dat
  • Importing PDS Members
  • Importing Non-Dynamic PDSs
  • Detecting the Data Set Type
  • Substituting Data Set Names in the Import Destination
  • Importing Relative to the Catalog File Folder
  • Creating a Log File
  • Performing a Bulk Import
  • Overwriting Existing Catalog Entries
  • Limiting the Number of VSAM Records to be Imported
  • Importing VSAM Files with Fixed Record Lengths
  • Converting to ASCII
  • Using UNIX Paths in the Catalog
Parent topic: Importing Data


Importing PDS Members

When you use the auto-catalog feature you can import an entire PDS and all of its members, whereas a regular import only supports the import of individual PDS members.

Example:

MFDAS IMPORT c:\mfi01.test.cobol\ FROM PDS mfi01.test.cobol /CATLOC=c:\proj\catalog.dat

Executing this command results in the following files being imported:

  • C:\MFI01.TEST.COBOL\ (PDS folder)
  • C:\MFI01.TEST.COBOL\VSAMDEMO (PDS member)
  • C:\MFI01.TEST.COBOL\VSAMDEM2 (PDS member)

The IMPORT command creates the folder mfi01.test.cobol\ if it does not already exist, adds a catalog entry for the PDS, then imports and catalogs the PDS members into that folder.

Parent topic: Importing Data with Auto-catalog


Importing Non-Dynamic PDSs

By default, an imported PDS is stored in the catalog as a dynamic PDS.

To import a PDS as a non-dynamic PDS you need to use the /NONDYNAMIC argument.

Example:

MFDAS IMPORT c:\mfi01.test.cobol\ FROM PDS mfi01.test.cobol /CATLOC=c:\proj\catalog.dat /NONDYNAMIC
Parent topic: Importing Data with Auto-catalog


Detecting the Data Set Type

You can specify the AUTO keyword in place of the data set type to indicate that the type of the imported data set is to be determined from the mainframe catalog. Using this feature means that you don't need to know what the data set type is in order to import and catalog it.

Example:

MFDAS IMPORT c:\mfi01.test.data.txt FROM AUTO mfi01.test.data /CATLOC=c:\proj\catalog.dat
Parent topic: Importing Data with Auto-catalog


Substituting Data Set Names in the Import Destination

You can use an asterisk in the import location (specified after the IMPORT keyword) to avoid having to manually specify the data set name as part of the target path.

Using an asterisk in the destination path causes the asterisk to be replaced by the data set name.

Example - QSAM:

MFDAS IMPORT c:\data\* FROM AUTO mfi01.test.data /CATLOC=c:\proj\catalog.dat

Executing this command results in the following file being imported:

  • c:\data\MFI01.TEST.DATA

Example - PDS:

MFDAS IMPORT c:\data\* FROM AUTO mfi01.test.cobol /CATLOC=c:\proj\catalog.dat

Executing this command results in the following files being imported:

  • C:\data\MFI01.TEST.COBOL\ (PDS folder)
  • C:\data\MFI01.TEST.COBOL\VSAMDEMO (PDS member)
  • C:\data\MFI01.TEST.COBOL\VSAMDEM2 (PDS member)
Parent topic: Importing Data with Auto-catalog


Importing Relative to the Catalog File Folder

If the import location that you specify starts with the <catalogfolder> keyword, the keyword is replaced by the path of the folder containing the catalog file specified by the /CATLOC argument.

You must enclose the import location in quotes when using the <catalogfolder> keyword.

Example:

MFDAS IMPORT "<catalogfolder>\data\*.*" FROM AUTO mfi01.test.cobol /CATLOC=c:\proj\catalog.dat

Executing this command results in the following files being imported:

  • c:\proj\data\MFI01.TEST.COBOL\ (PDS folder)
  • c:\proj\data\MFI01.TEST.COBOL\VSAMDEMO.CBL (PDS member)
  • c:\proj\data\MFI01.TEST.COBOL\VSAMDEM2.CBL (PDS member)
Parent topic: Importing Data with Auto-catalog


Creating a Log File

Use the /CATLOG=log-file-location argument to specify the location of a log file for the auto-catalog process.

You can control the level of messages that are written to the log file by using the /LOGLEVEL=msg-level argument:

  • /LOGLEVEL=ERROR specifies that only error messages are written to the log file.
  • /LOGLEVEL=VERBOSE specifies that additional messages are written.

Specifying /LOGLEVEL=ERROR can significantly reduce the size of the log file.

Parent topic: Importing Data with Auto-catalog


Performing a Bulk Import

The following steps outline how you could perform a bulk import.

  1. Run the MFDAS CAT command to obtain a list of data sets matching a filter and pipe the output to a file. For example:
    MFDAS CAT mfi01.test.c*> datasets.txt
  2. Create a batch file to run the MFDAS IMPORT command for each entry in the data set list file. For example:
    FOR /F %%A IN (datasets.txt) DO MFDAS IMPORT "<catalogfolder>\data\*.*" FROM AUTO %%A /CATLOC=c:\proj\catalog.dat
Parent topic: Importing Data with Auto-catalog


Overwriting Existing Catalog Entries

By default, the catalog import command overwrites existing entries in the catalog file unless the imported data set type differs from the data set type in the catalog. You can use the /OVERWRITE=overwrite-status argument to specify the behavior of catalog imports when a catalog entry for a data set already exists:

/OVERWRITE=N
forces the import to fail if a catalog entry for an imported data set already exists in the catalog.
/OVERWRITE=Y
forces any existing catalog entries to be overwritten.
Parent topic: Importing Data with Auto-catalog


Limiting the Number of VSAM Records to be Imported

Use the /NUMREC=record-number argument to limit the number of records that are to be imported from VSAM files.

Example:

The following command imports an ESDS data set but only downloads the first record:

MFDAS IMPORT "<catalogfolder>\data\*.*" FROM AUTO MFI01.TESTDC.ESDS /CATLOC=c:\proj\catalog.dat /NUMREC=1

Executing this command results in the following file being imported:

  • c:\proj\data\MFI01.TEST.COBOL\MFI01.TESTDC.ESDS.DAT
Parent topic: Importing Data with Auto-catalog


Importing VSAM Files with Fixed Record Lengths

Use the /FIXEDVSAM argument to import and catalog any VSAM file with a fixed record length.

Example:

MFDAS IMPORT "<catalogfolder>\data\*.*" FROM AUTO MFI01.TESTDC.ESDS /CATLOC=c:\proj\catalog.dat /FIXEDVSAM
Parent topic: Importing Data with Auto-catalog


Converting to ASCII

By default, imported data sets are imported as binary and remain in EBCDIC encoding. You can use the TEXT keyword to convert them to ASCII.

Specifying the TEXT keyword causes PDS and QSAM data sets to be converted to ASCII (in the process their record format is converted to LSEQ), and the catalog entries for these data sets have charset=A (ascii). You cannot use the TEXT keyword to translate VSAM data sets to ASCII.

Example:

MFDAS IMPORT TEXT c:\data\*.* FROM AUTO mfi01.test.cobol /CATLOC=c:\proj\catalog.dat
Parent topic: Importing Data with Auto-catalog


Using UNIX Paths in the Catalog

By default, files are added to the catalog with their workstation file location set to the same path they were downloaded to. You can override this path using the /CATOVERRIDE=unix-path argument.

The value of the /CATOVERRIDE argument replaces the <catalogfolder> token when the file is added to the catalog. This enables you to import files to a Windows folder, but store them in the catalog as a Unix path. For this to work, the download target must start with the <catalogfolder> token, as this token is replaced by the value of the /CATOVERRIDE argument.

Example:

The following command downloads the file mfi01.test.data to c:\proj\dir\mfi01.test.data but then sets the catalog entry workstation file location to /user/user1/dir/mfi01.test.data. This happens because <catalogfolder> in the import target is replaced with c:\proj while downloading, but is then replaced with /user/user1/ when adding the entry to the catalog.

MFDAS IMPORT "<catalogfolder>\dir\*" FROM AUTO mfi01.test.data /CATLOC=c:\proj\catalog.dat /CATOVERRIDE=/user/user1/
Parent topic: Importing Data with Auto-catalog


Exporting Data

You can export individual files, or a collection of files defined by a filter, to a partitioned data set or source code control system, or you can export entire QSAM data sets. You may optionally specify a control file containing one or more commands and allow MFDAS to run them as a batch. To do this, place the commands in a control file of any name, without the preceding MFDAS parameter, then run MFDAS with the parameter @filename, where filename is the name of the control file.

Note: You can configure user exits to perform actions after a successful export.

Text or binary transfers are possible. Use the BINARY or TEXT operand to override the default transfer type for the type. The default transfer type for PDS, Librarian, Panvalet or Endevor is TEXT. The default transfer type for QSAM is BINARY.

The FILENAME parameter can specify a specific workstation file name, or can included special filter characters to allow multiple exports to occur based on the special filter characters that you specify. If you use any of these special filter characters to cause one or more files to be exported, then you must specify the MEMBER parameter as an asterisk (*) as the member name will be replaced by the file name. These special filter characters are:

  • * means any characters may follow
  • ? means any character in this position

Example export commands are shown below.

PDS

To export to a Partitioned data set:

MFDAS EXPORT {BINARY | TEXT} {filename|filter} TO PDS
pdsname
MEMBER memname

Librarian

To export to a Librarian data set:

MFDAS EXPORT {BINARY | TEXT} {filename|filter} TO LIB
libname
MEMBER memname

Panvalet

To export to a Panvalet data set:

MFDAS EXPORT {BINARY | TEXT} {filename|filter} TO PAN
panname
MEMBER memname

Endevor

To export to an Endevor data set:

MFDAS EXPORT {BINARY | TEXT} {filename|filter} TO END
ENV 'env' SYS 'sys' SUB 'sub'
MEMBER memname
TYPE memtype
[CCID change-control-id]
[COMMENT user-comment]
[OVERRIDE SIGNOUT]
[LOCK={YES | NO}]
[COMMENT user-comment]
[BYPASS GEN]
[PGRP processor-group]
Note:

This command always exports to stage 1. You cannot use this command to promote a stage 1 entity to a stage 2 entity.

QSAM

To export to a QSAM data set:

MFDAS EXPORT {BINARY | TEXT} filename TO QSAM
qsamname
Parent topic: Using the Command Line Interface


Submitting Files

You can submit files, or a collection of files defined by a filter, to the mainframe internal reader for job execution. You may optionally specify a control file containing one or more commands and allow MFDAS to run them as a batch. To do this, place the commands in a control file of any name, without the preceding MFDAS parameter, then run MFDAS with the parameter @filename, where filename is the name of the control file. The format of the submit command is:

The FILENAME parameter can specify a specific workstation file name, or can included special filter characters to allow multiple submits to occur based on the special filter characters that you specify. These special filter characters are:

  • * means any characters may follow
  • ? means any character in this position

Example export commands are shown below.

MFDAS SUBMIT {filename|filter}

You can find out the status of all of your JOBS my issuing the STATUS command to the command line interface. The format of the status command is:

MFDAS STATUS
Parent topic: Using the Command Line Interface


Locating Data Sets

You can check to see whether a data set exists on the mainframe by using the locate command. A zero return code indicates that the data set exists, and a non-zero return code indicates that it does not exist. You may optionally specify a control file containing one or more commands and allow MFDAS to run them as a batch. To do this, place the commands in a control file of any name, without the preceding MFDAS parameter, then run MFDAS with the parameter @filename, where filename is the name of the control file. The format of the locate command is:

MFDAS LOCATE datasetname
Parent topic: Using the Command Line Interface


Retrieving Endevor Footprints

You can retrieve an Endevor footprint for one or all members in a PDS. The format of the command is as follows:

MFDAS DIR FOOT endevor.footprint.pds.dsname [FILTER membername]

where:

endevor.footprint.pds.dsname | is the dsname of the PDS containing the Endevor footprints.
membername | is the member whose footprint is to be returned. If omitted, footprints are returned for all members of the PDS.

The footprint information is returned inline in a 76-byte record as follows:

Information | Length
Member name | 16
Endevor type | 8
Date last modified | 8
Time last modified | 9
Version information | 10
Environment | 8
System | 8
SubSystem | 8
Stage | 1
Parent topic: Using the Command Line Interface


Changing Your Mainframe Password

You can change your mainframe password by entering the following command. A zero return code indicates that the password was changed, and a non-zero return code indicates that it was not successful. You may optionally specify a control file containing one or more commands and allow MFDAS to run them as a batch. To do this, place the commands in a control file of any name, without the preceding MFDAS parameter, then run MFDAS with the parameter @filename, where filename is the name of the control file. The format of the password command is:

MFDAS PASSWORD
newpassword
Parent topic: Using the Command Line Interface


Specifying Servers, Nodes and Ports

By default, when you run MFDAS from the command line it uses the server, node and port most recently specified by the Drag and Drop interface. You can, however, specify different settings to be used by the MFDAS command line by setting the MFA_SERVER_PARMS environment variable before running mfdas.exe. The format of this environment variable is as follows:

SET MFA_SERVER_PARMS=MFSRV:name,MFNODE:node,MFPORT:portnum

where:

name | is the name of the server to use. The example below specifies a server called MVSSRV.
node | is the URL to use or IP address to use. The example below specifies a URL of MVS.SERVER.COM.
portnum | is the port number to use. The example below specifies port number 6000.

Example:

SET MFA_SERVER_PARMS=MFSRV:MVSSRV,MFNODE:MVS.SERVER.COM,MFPORT:6000
Parent topic: Using the Command Line Interface


Displaying a Directory List

You can display a directory list of the files or members of the mainframe system catalog, a partitioned data set or source code control system. You may optionally specify a control file containing one or more commands and allow MFDAS to run them as a batch. To do this, place the commands in a control file of any name, without the preceding MFDAS parameter, then run MFDAS with the parameter @filename, where filename is the name of the control file.

The PREFIX parameter indicates that you are interesting in displaying only the members that begin with the specified characters. It is equivalent to using the FILTER parameter of the specified characters followed by an asterisk (*).

The FILTER parameter can specify a specific mainframe member name, or can included special filter characters to allow multiple members to be displayed based on the special filter characters that you specify. These special filter characters are:

  • * means any characters may follow
  • ? means any character in this position
  • + means the character in this position must be non-blank
  • - means the character in this position must be blank
  • \ means the character in this position must be non-numeric
  • / means the character in this position must be numeric

Examples of the directory list command are shown below.

CAT

To list data sets based upon a catalog search criteria:

MFDAS CAT
catalogsearchcriteria

CATDCB

To list the extended attributes for data sets based upon a catalog search criteria:

MFDAS CATDCB
catalogsearchcriteria

PDS

To list members of a partitioned data set:

MFDAS DIR PDS
pdsname [{PREFIX prefix | FILTER filter}]

Librarian

To list members of a Librarian data set:

MFDAS DIR LIB
libraryname [{PREFIX prefix | FILTER filter}]

Panvalet

To list members of a Panvalet data set:

MFDAS DIR PAN
libraryname [{PREFIX prefix | FILTER filter}]

Endevor

To list members of an Endevor data set:

MFDAS DIR END
ENV 'env' SYS 'sys' SUB 'sub'
[{PREFIX prefix | FILTER filter}]
[TYPE type]
Parent topic: Using the Command Line Interface


Using the Command Line Application Program Interface

You can invoke any of the command line interface options from within a COBOL program by executing the following code. Other programming languages, such as C, can be used to invoke the command line as well.

IDENTIFICATION DIVISION.
PROGRAM-ID. TESTCLIX.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.   IBM-PC.
OBJECT-COMPUTER.   IBM-PC.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 RESULT          PIC X      COMP-X.
01 FUNC            PIC X      COMP-X VALUE 35.
01 COMMAND.
   05 LEN          PIC X      COMP-X VALUE 10.
   05 PGM          PIC X(10) VALUE 'MFDAS.EXE'.
PROCEDURE DIVISION.
   DISPLAY "DIR PDS CSI01.JPD.CNTL" UPON COMMAND-LINE
   CALL X'91' USING RESULT FUNC COMMAND
   IF RESULT = 0
*>    EXECUTE SUCCESSFUL CODE HERE
   END-IF

On return, Drag and Drop sets the COBOL RESULT variable. The following return-codes are produced:

00 | Successful call
01 | An error was returned from MFLSC
14 | The program MFLSC is missing
15 | Call to DFCONV failed
48 | The mainframe member is locked by another user
49 | A mainframe ABEND occurred
50 | A dynamic allocation error occurred when accessing a data set
51 | An open error occurred on the mainframe
52 | An invalid request for a valid function was detected
53 | An I/O error has occurred on a mainframe data set
54 | An invalid sub-code was given to the mainframe
55 | A load error on a program on the mainframe was detected
56 | A length error, at a record level, has been detected
57 | A general security error has been detected
58 | A hash code mismatch has been detected
59 | The remote execution failed
60 | The JES spool file is not an output file
61 | The JES spool file is not a held output file
100 | Syntax error in call
125 | Too many concurrent users are active
139 | The record length was too large
218 | The DCB is not supported. This is usually caused by trying to use RECFM=U
219 | The mainframe load libraries are not APF authorized
220-241 | Various SAF security return codes
242 | The component in use has not been activated on the mainframe
243 | Unable to write the specified file to the workstation
244 | Unable to read the specified file from the workstation
245 | The catalog search detected an error
246 | The catalog search did not yield any results
247 | The /F MFENDDRV* statement was not in FHREDIR.CFG
248 | The /F MFLSCDRV* statement was not in FHREDIR.CFG
249 | The file FHREDIR.CFG could not be located
250 | A communications failure occurred
251 | The file did not have a positive length
252 | An invalid mask was given
253 | The local access mask was not specified
254 | The local access mode was not set
255 | Invalid function was requested
Parent topic: Using the Command Line Interface


MFDAS

Use the MFDAS command line utility to perform a range of file-related interactions with the mainframe.

Syntax

ALLOCATE
MFDAS ALLOCATE SEQ|PDS <dsname> CYL|TRK|BLK <number> LRECL <number> BLKSIZE <number>
RECFM F|V|U[B|S][A|M] [DIR <number>] [VOL <volser>]
CANCEL | HOLD | RELEASE
MFDAS CANCEL|HOLD|RELEASE <jobid>
CAT
MFDAS CAT <catalogsearchfilter>
CATDCB
MFDAS CATDCB <catalogsearchfilter> [JESDD JOB#]
COMPRESS
MFDAS COMPRESS <dsname>
DELETE
MFDAS DELETE <dsname> [MEMBER <mname>]
MFDAS DELETE JES <jobid> [PURGE]
DIR
MFDAS DIR END ENV <env> SYS <sys> SUB <sub> [PREFIX prefix|FILTER filter] [TYPE type]
MFDAS DIR FOOT <dsname> [FILTER <mname>]
MFDAS DIR JESDD <jobid>
MFDAS DIR LIB <dsname> [PREFIX <prefix>|FILTER <filter>]
MFDAS DIR PAN <dsname> [PREFIX <prefix>|FILTER <filter>] [USERCODE <code>]
MFDAS DIR PDS <dsname> [PREFIX <prefix>|FILTER <filter>]
EXPORT | CHECKIN
MFDAS EXPORT|CHECKIN [BINARY|TEXT] [RJSE] [NOTRANSLATE] <filename>|<filter> TO END ENV <env> SYS <sys>
SUB <sub > MEMBER <mname> TYPE <memtype> [CCID <change-control-id>] [COMMENT <user-comment>]
[OVERRIDE] [SIGNOUT] [BYPASS GEN] [PGRP <processor-group>] [LOCK=YES|NO]
MFDAS EXPORT|CHECKIN [BINARY|TEXT] [RJSE] [NOTRANSLATE] <filename>|<filter> TO LIB <dsname> MEMBER <mname>
MFDAS EXPORT|CHECKIN [BINARY|TEXT] [RJSE] [NOTRANSLATE] <filename>|<filter> TO PAN <dsname> MEMBER <mname>
[USERCODE <code>]
MFDAS EXPORT|CHECKIN [BINARY|TEXT]  [RJSE] [NOTRANSLATE] <filename>|<filter> TO PDS <dsname> MEMBER <mname>
[USERCODE <code>]
MFDAS EXPORT|CHECKIN [BINARY|TEXT]  [RJSE] [NOTRANSLATE] <filename> TO QSAM <dsname>
HELP
MFDAS HELP
IMPORT | CHECKOUT
MFDAS IMPORT|CHECKOUT [BINARY|TEXT] [RJSE] [NOTRANSLATE] <filename> FROM DB2 <dsname> <location> <authid>
<tablename>
MFDAS IMPORT|CHECKOUT [BINARY|TEXT] [RJSE] [NOTRANSLATE] <filename> FROM END ENV <env> SYS <sys> SUB <sub>
MEMBER <mname>|<filter> STG 1 TYPE <memtype> CCID <change-control-id> COMMENT <user-comment>
[OVERRIDE] [SIGNOUT] [LOCK=YES]
<tablename>
MFDAS IMPORT|CHECKOUT [BINARY|TEXT] [RJSE] [NOTRANSLATE] <filename> FROM ESDS|KSDS|RRDS[_FIXED] <dsname>
[NODFCONV]
MFDAS IMPORT|CHECKOUT [BINARY|TEXT] [RJSE] [NOTRANSLATE] <filename> FROM IMS <dsname> <databasename>
<segmentnamelocation> <segmentdatalocation>
MFDAS IMPORT|CHECKOUT [BINARY|TEXT] <filename> FROM JES <jobid>
MFDAS IMPORT|CHECKOUT [BINARY|TEXT] <filename> FROM JESDD <jes_ddname> JES <jobid>
MFDAS IMPORT|CHECKOUT [BINARY|TEXT] <filename> FROM LIB <dsname> MEMBER <mname>|<filter>
MFDAS IMPORT|CHECKOUT [BINARY|TEXT] <filename> FROM PAN <dsname> MEMBER <mname>|<filter>
MFDAS IMPORT|CHECKOUT [BINARY|TEXT] <filename> FROM PDS <dsname> MEMBER <mname>|<filter>
MFDAS IMPORT|CHECKOUT [BINARY|TEXT] <filename> FROM QSAM <dsname>
LOCATE
MFDAS LOCATE <dsname>
PASSWORD
MFDAS PASSWORD <password>
RECALL
MFDAS RECALL <dsname>
RENAME
MFDAS RENAME <dsname> MEMBER <mname> NEWNAME <mname>
SETUSER
MFDAS SETUSER <userid> <password>
SUBMIT
MFDAS SUBMIT <filename>|<filter>
STATUS
MFDAS STATUS [FILTER filter]
TERMINATE
MFDAS TERMINATE

Catalog parameters can appear anywhere, they are processed first and then removed:

  • /CAT=Y
  • /CATLOC=<filename>
  • /CATLOG=<filename>
  • /CATOVERRIDE=<catalogpath>
  • /ENDLOG=<endlogPath> - downloads the Endevor transaction log to the specified location on an END command failure
  • /FIXEDVSAM
  • /LOGLEVEL=ERROR|VERBOSE
  • /NONDYNAMIC
  • /NUMREC=<records to import>
  • /OVERWRITE=Y|N
  • /SHOWDETAILS
Parent topic: Using the Command Line Interface


Remote Job Step Execution

This chapter describes the Mainframe Remote Job Step Execution (RJSE) facility

  • Introduction
  • Configuring RJSE
  • Using RJSE
Parent topic: Using Enterprise Server with a Mainframe


Introduction

The Remote Job Step Execution (RJSE) facility enables execution of one or more steps of a job on a remote z/OS host. It automatically uploads and downloads required files as necessary with an end result the same as when all steps are executed locally.

Without the help of RJSE, you must execute a job step remotely if the resources required by the step are only available at the remote location. These resources could be any or all of the following:

  • Program(s), including those executed by the step that are either not available locally or are available locally but do not provide the required functions.
  • Special subsystems
  • Proprietary packages
  • Certain devices such as printers
  • Data, including data that is:
    • Too large to move
    • Heavily accessed
    • Stored in a proprietary format (for example, HISAM database)
    • On a special device
Parent topic: Remote Job Step Execution


Configuring RJSE

To use RJSE, you must configure your system as follows:

  1. Enable DataConnect for the project.
  2. Configure server access.
  3. To enable RJSE, set the MF_RCCF environment variable to one of the following values:
    • DELETEJOB - to keep all host job logs and the sysouts that have not been downloaded
    • KEEPJOB - to keep all host job logs and all sysouts
Parent topic: Remote Job Step Execution


Using RJSE

Use can use RJSE with all of its default settings or you can specify your own settings for the following components:

  • Programs
  • Datasets
  • Special DDs
  • RECFM=LSEQ Datasets

RJSE also provides a messaging system to trace execution and alert you of execution errors.

  • Programs
  • Datasets
  • Special DDs
  • RECFM=LSEQ Datasets
  • Host Step Execution Audit Trail
  • Error Messages
Parent topic: Remote Job Step Execution


Programs

Do one of the following to identify programs you want to execute on the host:

  • For each program that you want to execute on the host, code a job step that specifies host execution. Each step can be independent or within a PROC. For example, use a host-compatible JCL extension coded similar to the following:
    //SOMESTEP EXEC PGM=SOMEPGM,PARM='SOMEPARM'
//*MFE: %TYPEXEC=HOST
Parent topic: Using RJSE


Datasets

Datasets specified in steps that are executed on the host can reside either locally or on the host. By default, the RJSE facility automatically uploads or downloads datasets as necessary. However, if you want to override the default for one or more datasets, use the following JCL extensions:

  • %UPLOAD=[ YES | NO | AUTO ]
    • YES Upload the dataset referenced by the DD
    • NO Do not upload the dataset referenced by the DD
    • AUTO Let RJSE determine whether or not to upload the dataset referenced by the DD (default)
  • %DOWNLOAD=[ YES | NO | AUTO ]
    • YES Download the dataset referenced by the DD
    • NO Do not download the dataset referenced by the DD
    • AUTO Let RJSE determine whether or not to download the dataset referenced by the DD (default)
  • %PDSMEM=[ ALL | ONLY ]
    Use this in conjunction with %UPLOAD or %DOWNLOAD. RJSE ignores this setting if the dataset is not a PDS.

    • ALL Upload/Download the entire PDS of the dataset referenced by the DD
    • ONLY Upload/Download only the specified member of the dataset referenced by the DD (default)
Note: RJSE issues messages indicating the actions it performed to create, upload, download, and delete datasets. Use these to fine tune your dataset specifications.
Parent topic: Using RJSE


Special DDs

By default, RJSE neither uploads nor downloads datasets associated with the following DD statements:

  • SYSUDUMP
  • SYSABEND
  • SYSMDUMP
  • CEEDUMP
  • PLIDUMP
  • PL1DUMP
  • SYSCHK
  • SYSCKEOV
  • SORTLIB
  • JOBLIB
  • STEPLIB
  • JOBCAT
  • STEPCAT

You can override this default using the %UPLOAD and/or %DOWNLOAD JCL extensions as appropriate. For more information, see the section Datasets earlier in this chapter.

Parent topic: Using RJSE


RECFM=LSEQ Datasets

By default, when RJSE uploads RECFM=LSEQ datasets to the host, it uploads them as RECFM=FB datasets. To override this default, set the %LSEQRECF JCL extension keyword to specify which type of RECFM datasets to upload:

%LSEQRECF=[ V | VB | F | FB ]

Note: We strongly advise that you assign the LRECL for your local LSEQ dataset to an appropriate non-zero value. If you set the LSEQ dataset to a value of 0, RJSE generates a warning message and defaults to using a value of 80 for F and FB and 255 for V and VB which could lead to execution failures.
Parent topic: Using RJSE


Host Step Execution Audit Trail

For every step executed on the host, RJSE:

  • Issues messages indicating the actions it performed to create, upload, download, and delete datasets
  • Extracts select information from the host job log and inserts it into the local job log for the host-executed step
  • Downloads the host job log and spools it into in the local spool view under the DD name %ZJOBLOG.
Parent topic: Using RJSE


Error Messages

In rare cases, RJSE issues the following error messages:

  • JCLCM0118E Unexpected error from function RJSECA-FC-functionName RC=nnnnnnnn RS=nnnnnnnn.
  • JCLCM0119E Previous JCLCM0118E message is for DD/DSN ddname/datasetname.
  • JCLCM0121S Unexpected return type from RJSECA-FC-Execute %1$s.
  • JCLCM0122S Incorrect password caused SAF failure on the host.
  • JCLCM0123S Expired password caused SAF failure on the host.
  • JCLCM0124S Invalid user id caused SAF failure on the host.
  • JCLCM0125E %1$s is not supported.
  • JCLCM0126E %1$s is not yet supported.
  • JCLCM0127S Host dataset %1$s unexpectedly created by alien job.
  • JCLCM0128S Host dataset %1$s unexpectedly deleted by alien job.
  • JCLCM0129W LRECL of host RECFM F dataset %1$s assumed to be 80.
  • JCLCM0130W LRECL of host RECFM V dataset %1$s assumed to be 255.

If you get any JCLCMnnnns messages, please check the JCLCM Error Messages.

Parent topic: Using RJSE
Related reference
JCLCM Error Messages


Compare and Synchronization Monitor

Compare and Synchronization Monitor allows you to compare mainframe data sets against workstation directories. Where differences occur, you can synchronize the information. This can occur in either direction, or both directions. Typically, you would download mainframe partitioned data sets to a workstation directory.

  • What's new in this release
    What's new in version 2 of the Compare and Synchronization Monitor.
  • Starting Compare and Synchronization Monitor
    Start the Compare and Synchronization Monitor from the command line.
  • Configuring Compare and Synchronization Monitor
    Configure access to the mainframes with which you want to synchronize.
  • Synchronization and monitoring rules
    Set up rules to synchronize mainframe data sets against your workstation directories.
  • Advanced filters
    Create advanced filters to use regular expressions when synchronizing. The filters can be applied to your rules, to filter on specific members during synchronization.
  • Compare and Synchronization Monitor command line utility
    Use the command line utility to perform compare or synchronization without having to load the user interface.
  • Working directory
    Set the working directory to use the Compare and Synchronization Monitor files in that location.
  • Synchronization audit trail
    Display an audit trail of synchronization activity.
  • Compare and Synchronization Monitor legacy version
Parent topic: Using Enterprise Server with a Mainframe


What's new in this release

With the release of Enterprise Developer 2.2 Update 1, the Compare and Synchronization Monitor has been updated to version 2.

Version 2 is greatly improved in terms of performance, especially during initial checkout of partitioned data sets or when synchronizing a large number of members. Also, the user interface has been improved, and some of the functions available in the old version have now changed or become obsolete.

The rules that you set in the previous version are fully compatible with the new version, and automatically appear when you load the new interface.

In some cases, existing functionality has not yet been made available in the new version, but will continue to be added with each software release. Where the old functionality is still required, you can still access the previous version of Compare and Synchronization Monitor from the command line, using mfmonmx.

You will need to use the previous version if you still require one of the following features:
  • In-product scheduling
    Note: You can still create batch files and schedule them externally.
  • User exits
Parent topic: Compare and Synchronization Monitor


Starting Compare and Synchronization Monitor

You can start Compare and Synchronization Monitor from the command prompt.

  • Starting Compare and Synchronization Monitor from the command line
Parent topic: Compare and Synchronization Monitor


Starting Compare and Synchronization Monitor from the command line

To start Compare and Synchronization Monitor from an application command prompt, enter the following command:

MFMONMX2 [options]

where options is a combination of the following options:

/CFGFILE=filename
specifies the file (including path) that contains configuration information to be used by Compare and Synchronization Monitor. If you do not specify this option, Compare and Synchronization Monitor uses a file called mfmon2.cfg in the current directory.
/LOGFILE=filename
specifies the file (including path) to use for the output log file. If you do not specify this option, Compare and Synchronization Monitor uses a file called mfmon2.log in the current directory.
/RULEFILE=filename
specifies the file (including path) that contains filtering information to be used by Compare and Synchronization Monitor. If you do not specify this option, Compare and Synchronization Monitor uses a file called monrule2.ini first in the current directory.
Parent topic: Starting Compare and Synchronization Monitor


Configuring Compare and Synchronization Monitor

To synchronize your workstation with a mainframe, you need to set up a mainframe node. To do this, use the Server Access Configuration dialog box, which is used to configure communications settings for a number of other Mainframe Access components.

From this dialog box, you can view the status of the MFDaemon. The MFDaemon is a process that must be running to allow Compare and Synchronization Monitor and other Mainframe Access components to connect to a mainframe. If you stop the daemon from this dialog box, it will affect your Mainframe Access components.

You can also configure some of the aspects of the user interface, such as the menus and statuses that are displayed, and the appearance of the console log.

  • Configuring the appearance
Parent topic: Compare and Synchronization Monitor
Related concepts
About MFDaemon
Related information
Adding a Mainframe Node


Configuring the appearance

  1. Log on to MFA Compare and Synchronization Monitor:
    • From an Enterprise Developer command prompt, enter mfmonmx2.
  2. To display or hide the tool and status bars, on the View menu, select Tool Bar and Status Bar, as appropriate.
  3. To change the font used in the console log:
    1. On the View menu, click Choose Console Font.

      The Select Font dialog box appears.

    2. Select the required options from the Font Family and Style Weight Stretch lists.
    3. To increase or decrease the font size, use the slider beneath the Sample Text box.

    4. Click OK.
Parent topic: Configuring Compare and Synchronization Monitor


Synchronization and monitoring rules

Set up rules to synchronize mainframe data sets against your workstation directories.

Synchronization can occur in either direction, or both directions.

You can also create monitor rules, which mimic a synchronization rule, but don't actually update anything; view the audit trail to see the changes that would have been made.

Rules are stored in a configuration file, named mfmon2.cfg by default. You can use rules in a different configuration file by accessing Compare and Synchronization Monitor from the command line using the /CFGFILE option or by changing the current working directory once Compare and Synchronization Monitor is open.

When you use the [image] (Sync All Rules) option on the toolbar, all active rules are run. If you don't want to run certain rules, you can toggle their status to make them inactive, or you can run the required rules individually using the right-click menu.

  • Adding a rule
  • Modifying a rule
  • Removing a rule
  • Synchronizing rules
  • Toggling active status of a rule
Parent topic: Compare and Synchronization Monitor
Related concepts
Working directory
Related information
Starting Compare and Synchronization Monitor from the command line


Adding a rule

  1. Log on to MFA Compare and Synchronization Monitor:
    • From an Enterprise Developer command prompt, enter mfmonmx2.
  2. On the main toolbar, click Add rule (Add new rule).

    The Check Data Set Type dialog box appears.

  3. Type the name of the data set to synchronize, set the organization type (if required), then click OK.

    If the data set is valid, the Add Rule dialog screen appears.

  4. Click the box below Sync Mode and select one of the following:
    • BOTH - changes on either the mainframe or the workstation are synchronized
    • UPLOAD - only changes on the workstation are synchronized to the mainframe
    • DOWNLOAD - only changes on the mainframe are synchronized to the workstation
    • MONITOR - mimics the BOTH setting without changes being made
  5. Click Binary Data Transfer to transfer PDS data sets in binary format.
  6. In the Member Type field, specify the type of member contained in an Endevor, Panvalet or Librarian container, if appropriate.
  7. If required, click Advanced and select one or more of the following options:
    Note: These options apply to all active rules.
    • Delete workstation file if mainframe member is deleted - during synchronization, if a member has been deleted on the mainframe, it will also be deleted on the workstation.
    • Delete workstation folder if library is deleted - during synchronization, if a library has been deleted on the mainframe, the workstation folder is also deleted if it contains no other synchronized members.
    • Handle embedded hex in MF MDECONV format - uses the MDECONV technique to deal with embedded hex values, that is, all translated hex values less than x'1f' have a null character inserted before the hex value, and the COBOL run-time system handles these embedded hex values.
    • Suppress embedded hex warning messages - pop-up messages when a non-printing character is received from the mainframe are not displayed; an entry is recorded in the log file instead.
  8. If required, click Filters, then add a simple or advanced filter:
    • To add a simple filter, in the Simple Filter field, enter a filter (for example AA* filters only on data sets that start AA), then click OK.
    • To add an advanced filter, click Use Advanced Filters, Add Filters, click the required filter and select how the filter should work (Include or Exclude), then click OK.
  9. In the Directory field, enter the path of a workstation directiory to use for synchronization.
  10. In the File Extension field, enter the extension that will be applied to each member synchronized to the workstation.
  11. Click OK.

    The rule appears on the main screen.

Parent topic: Synchronization and monitoring rules
Related tasks
Modifying a rule
Removing a rule
Synchronizing rules
Toggling active status of a rule
Adding an advanced filter
Related information
Handling Embedded HEX Values


Modifying a rule

  1. Log on to MFA Compare and Synchronization Monitor:
    • From an Enterprise Developer command prompt, enter mfmonmx2.
  2. On the main toolbar, select an existing rule, then click Modify rule (Modify rule).

    The Modify Rule dialog box appears.

  3. Edit the rule details, as appropriate.
    Tip: To remove an advanced filter, right-click the required filter, then click Remove.
  4. Click OK.
Parent topic: Synchronization and monitoring rules
Related tasks
Adding a rule
Removing a rule
Synchronizing rules
Toggling active status of a rule


Removing a rule

  1. Log on to MFA Compare and Synchronization Monitor:
    • From an Enterprise Developer command prompt, enter mfmonmx2.
  2. On the main toolbar, select an existing rule, then click Delete rule (Remove rule).

    The rule is removed from the main screen.

Parent topic: Synchronization and monitoring rules
Related tasks
Adding a rule
Modifying a rule
Synchronizing rules
Toggling active status of a rule


Synchronizing rules

  1. Log on to MFA Compare and Synchronization Monitor:
    • From an Enterprise Developer command prompt, enter mfmonmx2.
  2. On the main toolbar, click Synchronize rules (Sync All Rules).
  3. If this is the first time you have synched, you are prompted to enter the mainframe logon credentials; enter the credentials, then click OK.

    All active rules are synchronized.

    Note: To synchronize rules individually, right-click a rule and choose Sync.
  4. While the synchronization is in progress, you can click Cancel synchronization to cancel it.

    Any remaining members are not synchronized.

Parent topic: Synchronization and monitoring rules
Related tasks
Adding a rule
Modifying a rule
Removing a rule
Toggling active status of a rule


Toggling active status of a rule

  1. Log on to MFA Compare and Synchronization Monitor:
    • From an Enterprise Developer command prompt, enter mfmonmx2.
  2. On the main toolbar, select an existing rule, then click Toggle rule status (Toggle rule's active status).

    The status of the rule is toggled. Inactive rules appear grayed out.

Parent topic: Synchronization and monitoring rules
Related tasks
Adding a rule
Modifying a rule
Removing a rule
Synchronizing rules


Advanced filters

Create a library of advanced filters that you can use in your synchronization rules. An advanced filter contains a regular expression, which is used to filter on specific data sets during synchronization.

  • Adding an advanced filter
  • Editing an advanced filter
  • Removing an advanced filter
Parent topic: Compare and Synchronization Monitor


Adding an advanced filter

  1. Log on to MFA Compare and Synchronization Monitor:
    • From an Enterprise Developer command prompt, enter mfmonmx2.
  2. On the Options menu, click Add Advanced Filters.

    The Add Advanced Filter dialog box appears.

  3. Click Add.

    The Add Filter Rule dialog box appears.

  4. In the Name field, type a name for the filter rule.
  5. In the Expression field, enter a regular expression.
  6. In the Description field, enter a description of the filter rule.
  7. Click OK.

    The filter is added. When you add a rule, you can use the filter to include or exclude members based on the filter criteria.

Parent topic: Advanced filters
Related tasks
Editing an advanced filter
Removing an advanced filter
Adding a rule


Editing an advanced filter

  1. Log on to MFA Compare and Synchronization Monitor:
    • From an Enterprise Developer command prompt, enter mfmonmx2.
  2. On the Options menu, click Add Advanced Filters.

    The Add Advanced Filter dialog box appears.

  3. Right-click the required filter, then select Modify.

    The Add Filter Rule dialog box appears.

  4. Edit the details, as appropriate, then click OK.

    The filter is modified.

Parent topic: Advanced filters
Related tasks
Adding an advanced filter
Removing an advanced filter


Removing an advanced filter

  1. Log on to MFA Compare and Synchronization Monitor:
    • From an Enterprise Developer command prompt, enter mfmonmx2.
  2. On the Options menu, click Add Advanced Filters.

    The Add Advanced Filter dialog box appears.

  3. Right-click the required filter, then select Remove.

    The filter is removed.

Parent topic: Advanced filters
Related tasks
Adding an advanced filter
Editing an advanced filter


Compare and Synchronization Monitor command line utility

Use the command line utility to perform compare or synchronization without having to load the user interface.

You can run the utility directly from the command prompt, or add commands to a batch file, then use a scheduler to run the batch file.

Syntax:

>>-MFMON2--.--------.--.-BOTH-----.--.----------.--.-QSAM-.--local-dir->
           +-TEXT---+  +-UPLOAD---+  +-prefix-*-+  +-PDS--+
           +-BINARY-+  +-DOWNLOAD-+                +-END--+
                       +-MONITOR--+                +-KSDS-+

>-AGAINST-data-set--.---------------.-.------------.-.---------------.->
                    +-TYPE=mem-type-+ +-STATUS=xxx-+ +-EXT=extension-+

>-.----------------.---<<
  +-REGEXT_ALLOW=Y-+

Where:

prefix
The filter to use to select files and members. By default, * selects all.
local-dir
The directory on the workstation
data-set
The data set on the mainframe
TYPE=mem-type
The type of member contained in an Endevor, Panvalet or Librarian container.
STATUS=xxx
The status of Panvalet members
EXT=extension
The extension to give each synchronized member on the workstation
REGEXT_ALLOW=Y
Allows the prefix to be in the format of a regular expression.

Comments:

To ensure the utility can connect to the mainframe without user intervention, set the MFA_SERVER_PARMS environment variable and the MFDAS SETUSER command at the head of your batch file, or from the command line. For example:
SET MFA_SERVER_PARMS=MFSRV:mf01,MFNODE:mf01.docs.com,MFPORT:1234
MFDAS SETUSER usr1 pass1
  • Command line utility examples
Parent topic: Compare and Synchronization Monitor
Related information
Specifying Servers, Nodes and Ports


Command line utility examples

MFMON2 DOWNLOAD PDS C:\TEMP\SYNC\ AGAINST MFI01.COMMS.TEST.SYNCB.CNTL EXTENSION=CNTL

Synchronizes the members in C:\TEMP\SYNC against the contents of MFI01.COMMS.TEST.SYNCB.CNTL, giving each member in that directory a .CNTL extension.

MFMON2 MONITOR PREFIX ABC LIBRARIAN C:\DEMO\*.* AGAINST LIBR.MASTER

Monitors the members in the LIBR.MASTER Librarian container against the contents of C:\DEMO, recording details in the log file of those items prefixed ABC that would have been synchronized.

Parent topic: Compare and Synchronization Monitor command line utility


Working directory

If you have not started Compare and Synchronization Monitor from the command line specifying a configuration file, filter file, or log file, Compare and Synchronization Monitor uses a default location of the current working directory for these files.

The default files are:

File | Description
mfmon2.cfg | Contains the monitor and synchronization rules
monrule2.ini | Contains the filters that can be applied to rules
mfmon2.log | Contains an audit trail of synchronization activity

If these files do not already exist, they are created when you add a rule or filter, or synchronize.

Use the Change Directory option to set your own folder to use each time Compare and Synchronization Monitor is started. If you have multiple versions of these files, in different locations, you can also use this option to switch between locations and synchronize the different sets of rules.

  • Changing the working directory
Parent topic: Compare and Synchronization Monitor
Related concepts
Synchronization and monitoring rules
Related information
Starting Compare and Synchronization Monitor from the command line


Changing the working directory

  1. Log on to MFA Compare and Synchronization Monitor:
    • From an Enterprise Developer command prompt, enter mfmonmx2.
  2. On the File menu, click Change Directory.

    The Browse for Folder dialog box appears.

  3. Select the required directory, then click OK.

    The default configuration (mfmon2.cfg), filter (monrule2.ini), and logging (mfmon2.log) files in that directory are now used.

Parent topic: Working directory


Synchronization audit trail

The Sync Console displays an audit trail of synchronization activity since Compare and Synchronization Monitor was last started, but if you want to view information from previous sessions, view the log file.

By default, the log file is named mfmon2.log, but you can log activity to a new log file by accessing Compare and Synchronization Monitor from the command line using the /LOGFILE option and specifying a new log file, or changing the working directory.

  • Browsing the log file
Parent topic: Compare and Synchronization Monitor
Related information
Starting Compare and Synchronization Monitor from the command line
Working directory
Changing the working directory


Browsing the log file

  1. Log on to the MFA Compare and Synchronization Monitor.
    • From an Enterprise Developer command prompt, enter mfmonmx2.
  2. On the File menu, choose Browse Log File.

    The latest log file appears in Notepad.

    Note: Log details from the current session also appear in the Sync Console:

Parent topic: Synchronization audit trail
Related information
Working directory
Changing the working directory


Compare and Synchronization Monitor legacy version

Note: This section covers the legacy version of the Compare and Synchronization Monitor. For details on the newer version, see Compare and Synchronize Monitor and What's new in the latest version.

Compare and Synchronization Monitor allows you to mirror mainframe data sets against workstation directories. This mirroring, known as synchronizing, can occur in either direction, or both directions. Typically, a user would synchronize mainframe partitioned data sets with a workstation directory for download.

  • Starting Compare and Synchronization Monitor
  • Configuring Compare and Synchronization Monitor
  • Log Output
  • Error Message Output
Parent topic: Compare and Synchronization Monitor


Starting Compare and Synchronization Monitor

Note: This section covers the legacy version of the Compare and Synchronization Monitor. For details on the newer version, see Compare and Synchronize Monitor and What's new in the latest version.

You can start Compare and Synchronization Monitor from the command prompt. The command prompt method provides options for configuring Compare and Synchronization Monitor.

  • Starting Compare and Synchronization Monitor from the Command Line
Parent topic: Compare and Synchronization Monitor legacy version


Starting Compare and Synchronization Monitor from the Command Line

To start Compare and Synchronization Monitor from the command line, from the application command prompt, enter the following command:

MFMONMX [options]

where options is any combination of the following options:

/AUTOLOGON
specifies that the Compare and Synchronization Monitor Utility is to call the MFDASPWD user exit. See the section Providing Your Own Security Exit to The Command Line Interface for more information on MFDASPWD.
/CFGFILE=filename
specifies the file (including a path) that contains configuration information to be used by Compare and Synchronization Monitor. If you do not specify this option, Compare and Synchronization Monitor looks for a file called mfmon.cfg first in the current directory, then in the directory containing mfmonmx.exe.
/DATFILE=filename
specifies the name (including full path) of the database.
/ERRFILE=filename
specifies the name (including full path) to use for the error message output file. The default name of this file is MFMON.ERR.
/LOGFILE=filename
specifies the name (including path) to use for the output log file. The default name of this file is MFMON.LOG.
/NOGUI
specifies that Compare and Synchronization Monitor is to run without displaying its graphical interface. If you use this option, you will need to use your operating system's Task Manager to close Compare and Synchronization Monitor.
/NOPROCESS
specifies that Compare and Synchronization Monitor will not try to access the mainframe when started. This enables you to change configuration options when you do not have a mainframe connection.
/PASS=password
specifies the mainframe password to use. Specifying the password and user ID from the command line means you will not be prompted for this information when Compare and Synchronization Monitor starts.
/RULEFILE=filename
specifies the file (including a path) that contains filtering information to be used by Compare and Synchronization Monitor. If you do not specify this option, Compare and Synchronization Monitor looks for a file called monrule.ini first in the current directory, then in the directory containing mfmonmx.exe.
/USER=userid
specifies the mainframe user ID to use.
Note: If you need to start Compare and Synchronization Monitor from a directory other than the one containing mfmonmx.exe, prefix the command with the fully qualified path of the directory containing mfmonmx.exe. For example, if mfmonmx.exe was installed into d:\mfa\bin, use the following command to start Compare and Synchronization Monitor:
d:\mfa\bin\mfmonmx [options]

Once started, the interactive configuration takes place for first time users. Subsequent configuration invocations can take place by using the Configure options pulldown.

Parent topic: Starting Compare and Synchronization Monitor


Configuring Compare and Synchronization Monitor

Note: This section covers the legacy version of the Compare and Synchronization Monitor. For details on the newer version, see Compare and Synchronize Monitor and What's new in the latest version.

Compare and Synchronization Monitor uses a configuration file as input to its processor. This configuration file, MFMON.CFG, contains the necessary statements to allow Compare and Synchronization Monitor to set up the proper synchronization between any number of workstation directories and mainframe data sets, or source code control systems. This configuration file must be located in the directory that you start up the monitor in. This is your current working directory.

You can configure MFMON.CFG in two ways:

  • Using the graphical interactive configuration tools. This is the simplest and recommended method for updating MFMON.CFG in most cases. The configuration tools are accessed from the configure options pulldown or the monitor, and take you through the necessary steps to define your environment. Typically you would click the add button on the bottom of the dialog box to add a new relationship. Online help is available for all dialog boxes within the configuration tool by clicking the Help button.
  • Manual editing. Although you can use the graphical tools to control all aspects of the Compare and Compare and Synchronization Monitor's behavior, there are situations where it is quicker to edit MFMON.CFG manually. For instance, you might want to add a large number of data sets, or you might want to maintain different versions of MFMON.CFG for different purposes.
  • MFMON.CFG Statements
  • Example MFMON.CFG Statements
Parent topic: Compare and Synchronization Monitor legacy version


MFMON.CFG Statements

The statements you can specify in MFMON.CFG are described below.

  • ALLOW
  • AUTORECONNECT
  • COMMENT
  • MONITOR
  • PERFORM
  • STARTUP
  • TITLE
  • TRANSFERLIMIT
  • WAKEUP
Parent topic: Configuring Compare and Synchronization Monitor


ALLOW

Syntax

ALLOW WORKSTATION DELETES

Specifies whether the Compare and Synchronize Monitor is to delete workstation files when it notices that the corresponding mainframe member has been deleted.

Parameters

None

Comments

The default is not to delete the workstation files.

Parent topic: MFMON.CFG Statements
Related reference
AUTORECONNECT
COMMENT
MONITOR
PERFORM
STARTUP
TITLE
TRANSFERLIMIT
WAKEUP


AUTORECONNECT

Syntax

AUTORECONNECT requests

Specifies whether the Compare and Synchronize Monitor is to automatically terminate the connection to the mainframe and then initiate a new connection after a specified number of mainframe server requests.

Parameters

requests
The number of requests to fulfill before initiating a new connection. A typical value is 500.

Comments

The AUTORECONNECT statement is useful to overcome memory leaks that can occur when some mainframe source code control systems and operating system functions are called.

Parent topic: MFMON.CFG Statements
Related reference
ALLOW
COMMENT
MONITOR
PERFORM
STARTUP
TITLE
TRANSFERLIMIT
WAKEUP


COMMENT

Syntax

* comment

The comment statement is ignored by the Compare and Synchronize Monitor. Any statement beginning with an asterisk '*' is treated as a comment.

Parameters

comment Any text.

Parent topic: MFMON.CFG Statements
Related reference
ALLOW
AUTORECONNECT
MONITOR
PERFORM
STARTUP
TITLE
TRANSFERLIMIT
WAKEUP


MONITOR

Syntax

MONITOR[PVCS]
[BINARY]
direction [PREFIX filter]
dataset-type
drive:\directory\*.ext
AGAINST mainframe-parameters

Specifies which workstation directories (when MONITOR is used) or PVCS archives (when MONITORPVCS is used) are to be monitored against which mainframe data sets or source code control systems. Any number of these statements can be placed in the configuration file as desired.

Parameters

BINARY
Specifies that you do not want the Compare and Synchronize Monitor to perform any EBCDIC/ASCII translation. This option is useful if you have a PDS containing binary data, and is only available if you have set dataset-type to PDS or PARTITIONED. Synchronization of binary members is based on time stamps.
direction
The directions that the Compare and Synchronize Monitor is to monitor. This can be one of:
  • NONE

    Monitor, but do not allow an upload or download to occur. This produces a report only.

  • DOWNLOAD

    Monitor, but do not allow an upload to occur. This will allow download synchronization to occur.

  • UPLOAD

    Monitor, but do not allow a download to occur. This will allow upload synchronization to occur. This option is not applicable if dataset-type is VSAM-KSDS, VSAM-KSDS-FIXED, VSAM-ESDS, VSAM-ESDS-FIXED, VSAM-RRDS or VSAM-RRDS-FIXED.

  • BOTH

    Monitor, and allow both uploads and downloads to occur. This option is not applicable if dataset-type is VSAM-KSDS, VSAM-KSDS-FIXED, VSAM-ESDS, VSAM-ESDS-FIXED, VSAM-RRDS or VSAM-RRDS-FIXED.

filter
A specific member name or filter characters to specify a collection of members to be monitored. You can embed the filter characters with any other characters for pattern matching of the member name, similar to the usage of the wildcard characters on the workstation dir command:
  • * any character may follow
  • ? any character in this position
  • + the character in this position must be non-blank
  • - the character in this position must be a blank
  • / the character in this position must be numeric
  • \ the character in this position must be non-numeric

The value for filter can be from 1 to 16 characters long.

This parameter is optional when dataset-type is PDS (or PARTITIONED), LIBRARIAN, PANVALET and ENDEVOR, and is not applicable when dataset-type is set to anything else.

dataset-type
The type of the mainframe data set for which a monitoring relationship is to be built. This can be one of:
  • PDS

    Partitioned data set. Specifying PARTITIONED has the same effect as specifying PDS.

  • LIBRARIAN

    Computer Associates Librarian data set.

  • PANVALET

    Computer Associates Panvalet data set.

  • ENDEVOR

    Computer Associates Endevor data set.

  • SEQUENTIAL

    Sequential data set.

  • VSAM-KSDS

    Keyed (VSAM KSDS) data set. You cannot use MONITORPVCS when dataset-type is set to VSAM-KSDS.

    Set dataset-type to VSAM-KSDS if you want to monitor Innovation Access Method (IAM) files.

  • VSAM-ESDS

    Entry (VSAM ESDS) data set. You cannot use MONITORPVCS when dataset-type is set to VSAM-ESDS.

  • VSAM-RRDS

    Relative (VSAM RRDS) data set. You cannot use MONITORPVCS when dataset-type is set to VSAM-RRDS.

  • VSAM-KSDS-FIXED

    Keyed (VSAM KSDS) data set, where the resulting imported file is converted to Micro Focus format in fixed format, with the minimum record length set to the maximum record length. You cannot use MONITORPVCS when dataset-type is set to VSAM-KSDS-FIXED.

  • VSAM-ESDS-FIXED

    Entry (VSAM ESDS) data set, where the resulting imported file is converted to Micro Focus format in fixed format, with the minimum record length set to the maximum record length. You cannot use MONITORPVCS when dataset-type is set to VSAM-ESDS-FIXED.

  • VSAM-RRDS-FIXED

    Relative (VSAM RRDS) data set, where the resulting imported file is converted to Micro Focus format in fixed format, with the minimum record length set to the maximum record length. You cannot use MONITORPVCS when dataset-type is set to VSAM-RRDS-FIXED.

drive:\directory\*.ext
When using MONITOR, specify the fully qualified path and name of the workstation files to complete the monitor relationship. You must specify the specific extension, such as *.CBL, to be monitored against.

If you specify the extension as three asterisks (***), the download initially downloads the file with no extension. If the file extension is then changed, the next synchronization operation finds the first matching filename with any extension. Only one file with the same filename can exist in the target directory. For example, if a host PDS member name is ACCTOPEN and no file with the prefix ACCTOPEN exists in the PC target directory, the file is downloaded as ACCTOPEN. If the extension is then modified to ACCTOPEN.CBL, the next synchronization detects the target filename as ACCTOPEN.CBL and synchronizes against that.

When using MONITORPVCS, specify the fully qualified location of a PVCS archive configuration file to complete the monitor relationship. This is the name of the archive in the usual archivename.cfg format.

mainframe-parameters
Parameters defining the data sets on the mainframe. The parameters to be specified vary depending on the setting of dataset-type:

  • When dataset-type is PDS, PARTITIONED, SEQUENTIAL, VSAM-KSDS, VSAM-KSDS-FIXED, VSAM-ESDS, VSAM-ESDS-FIXED, VSAM-RRDS or VSAM-RRDS-FIXED, the format of mainframe-parameters is as follows:
    dataset
EXTENSION=extension
    where the parameters are:
    • dataset The name of the dataset to be monitored.
    • extension The extension of the datset to be monitored. This is optional.
  • When dataset-type is ENDEVOR, the format of mainframe-parameters is as follows:
    ENV 'environment' SYS
'system' SUB 'subsystem'
STG 'stage' TYPE=type
CCID=ccid COMMENT=comment
EXTENSION=extension

    where the parameters are:

    • environment

      The Endevor environment to be monitored.

    • system

      The Endevor system to be monitored.

    • subsystem

      The Endevor subsystem to be monitored.

    • stage

      The Endevor stage to be monitored. Must be 1 or 2.

    • type

      The Endevor type to be monitored.

    • ccid

      Change control ID.

    • comment

      Comment text.

  • When dataset-type is LIBRARIAN or PANVALET, the format of mainframe-parameters is as follows:
    dataset
[TYPE=type]
EXTENSION=ext

    where the parameters are:

    • dataset

      The fully qualified name of the data set to be monitored.

    • type
      Optional specific member types for your monitor relationship (if your installation has been set up to use valid Panvalet or Librarian types on the mainframe). You can specify a specific type, or use filter characters to be creative about a collection of types to be monitored. You can embed the filter characters with any other characters for pattern matching, similar to the usage of the wildcard characters on the workstation dir command: * any character may follow
      • ? any character in this position
      • + the character in this position must be non-blank
      • - the character in this position must be a blank
      • / the character in this position must be numeric
      • \ the character in this position must be non-numeric
  • ext

    The extension of the files to be monitored.

Parent topic: MFMON.CFG Statements
Related reference
ALLOW
AUTORECONNECT
COMMENT
PERFORM
STARTUP
TITLE
TRANSFERLIMIT
WAKEUP


PERFORM

Syntax

PERFORM
nnnn TIME[S]

Specifies the number of times the Compare and Synchronize Monitor is to perform the analysis scan.

Parameters

nnnn
The number of times to perform the analysis scan.

Comments

If you do not specify a PERFORM statement, monitoring takes place indefinitely

Parent topic: MFMON.CFG Statements
Related reference
ALLOW
AUTORECONNECT
COMMENT
MONITOR
STARTUP
TITLE
TRANSFERLIMIT
WAKEUP


STARTUP

Syntax

STARTUP
hh:mm

Specifies that the Compare and Synchronize Monitor is to start up at a specified time.

Parameters

hh:mm
The time at which the Compare and Synchronize Monitor is to start up. The format is in 24-hour time, so must be in the range 00:00 through 23:59.

Comments

If you specify a time that has already elapsed today, the task starts the following day. The STARTUP statement is generally used in conjunction with the WAKEUP statement.

Parent topic: MFMON.CFG Statements
Related reference
ALLOW
AUTORECONNECT
COMMENT
MONITOR
PERFORM
TITLE
TRANSFERLIMIT
WAKEUP


TITLE

Syntax

TITLE
title-text

Specifies the text to display in the Compare and Synchronize Monitor title bar. This allows you to easily identify a specific monitor session from the task list.

Parameters

title-text
The text to be displayed in the title bar.
Parent topic: MFMON.CFG Statements
Related reference
ALLOW
AUTORECONNECT
COMMENT
MONITOR
PERFORM
STARTUP
TRANSFERLIMIT
WAKEUP


TRANSFERLIMIT

Syntax

TRANSFERLIMIT
limit

Specifies a limit on the number of imports or exports the Compare and Synchronize Monitor performs per cycle.

Parameters

limit
The number of of imports or exports to perform per cycle.

Comments

If you do not specify a TRANSFERLIMIT statement, all required files are transferred.

Parent topic: MFMON.CFG Statements
Related reference
ALLOW
AUTORECONNECT
COMMENT
MONITOR
PERFORM
STARTUP
TITLE
WAKEUP


WAKEUP

Syntax

WAKEUP
nnnn {SECOND[S] | MINUTE[S] | HOUR[S] |
DAY[S]}

Specifies how long the Compare and Synchronize Monitor is to remain dormant after the initial analysis has completed but before analyzing the environment for subsequent changes to be processed.

Parameters

nnnn
The number of seconds, minutes, hours or days to wait between completing the initial analysis and analyzing the environment for subsequent changes.

Comments

If you do not specify a WAKEUP statement, the default is to remain dormant for 8 hours.

Parent topic: MFMON.CFG Statements
Related reference
ALLOW
AUTORECONNECT
COMMENT
MONITOR
PERFORM
STARTUP
TITLE
TRANSFERLIMIT


Example MFMON.CFG Statements

The following examples show typical statements that might be used in an MFMON.CFG file:

  • To monitor a workstation directory for files that have an extension of CBL against a partitioned data set for both upload and download:
    MONITOR BOTH PARTITIONED
C:\DEMO\*.CBL AGAINST SYS1.COBOL.SOURCE
  • To monitor a Librarian data set for download only for all members beginning with ABC:
    MONITOR
DOWNLOAD PREFIX ABC LIBRARIAN C:\DEMO\*.* AGAINST LIBR.MASTER
  • To monitor an Endevor data set for both upload and download for all members in of Endevor type CBL:
    MONITOR BOTH ENDEVOR C:\DEMO\*.CBL AGAINST ENV
'PROD' SYS 'SYST' SUB 'SUBS' TYPE=CBL CCID=userccid
COMMENT=user.comment.field
Parent topic: Configuring Compare and Synchronization Monitor


Log Output

Note: This section covers the legacy version of the Compare and Synchronization Monitor. For details on the newer version, see Compare and Synchronize Monitor and What's new in the latest version.

All successful actions and files that were successfully transmitted will be logged in the output log named MFMON.LOG.

Parent topic: Compare and Synchronization Monitor legacy version


Error Message Output

Note: This section covers the legacy version of the Compare and Synchronization Monitor. For details on the newer version, see Compare and Synchronize Monitor and What's new in the latest version.

All errors and files that were not successfully transmitted will be logged in the error message output log named MFMON.ERR.

  • User exit after a successful import
  • User exit after a successful export
  • User exit before a workstation delete
  • User exit after a workstation delete
  • User exit after all synchronization has been done
Parent topic: Compare and Synchronization Monitor legacy version


User exit after a successful import

After each successful import of a member from the mainframe, a user exit is called and if it exists, it will be passed the following 3 parameter addresses:

  • A 256 byte area containing the fully qualified name of the workstation file that was just created from the import
  • A 160 byte area containing the mainframe data set name or parameters used in the import
  • A 19 byte area containing the 16 byte mainframe member name used in the import, and a 3 byte field containing ADD if this was a new member being imported, or REP if this was a replacement member being imported.

You may write your own user exit in COBOL if you desire. The name of the program must be MFMONIMP.

IDENTIFICATION DIVISION.
PROGRAM-ID. MFMONIMP.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.    IBM-PC.
OBJECT-COMPUTER.    IBM-PC.
DATA DIVISION.
LINKAGE SECTION.
01 P-WORKSTATION    PIC X(256).
01 P-DATASETNAME    PIC X(160).
01 P-MEMBERAREA.
   05 P-MEMBERNAME  PIC X(16).
   05 P-MEMBERFLAG  PIC X(3).
PROCEDURE DIVISION USING P-WORKSTATION P-DATASETNAME
                         P-MEMBERAREA.
*> EXECUTE CODE HERE
   GOBACK.
Parent topic: Error Message Output


User exit after a successful export

After each successful export of a member to the mainframe, a user exit is called and if it exists, it will be passed the following 3 parameter addresses:

  • A 256 byte area containing the fully qualified name of the workstation file that was used in the export
  • A 160 byte area containing the mainframe data set name or parameters used in the export
  • A 19 byte area containing the 16 byte mainframe member name used in the export, and a 3 byte field containing ADD if this was a new member being exported, or REP if this was a replacement member being exported.

You may write your own user exit in COBOL if you desire. The name of the program must be MFMONEXP.

IDENTIFICATION DIVISION.
PROGRAM-ID. MFMONEXP.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.     IBM-PC.
OBJECT-COMPUTER.     IBM-PC.
DATA DIVISION.
LINKAGE SECTION.
01 P-WORKSTATION     PIC X(256).
01 P-DATASETNAME     PIC X(160).
01 P-MEMBERAREA.
   05 P-MEMBERNAME   PIC X(16).
   05 P-MEMBERFLAG   PIC X(3).
PROCEDURE DIVISION USING P-WORKSTATION P-DATASETNAME
                         P-MEMBERAREA.
*> EXECUTE CODE HERE
   GOBACK.
Parent topic: Error Message Output


User exit before a workstation delete

If the ALLOW WORKSTATION DELETES option is on, a user exit is called and if it exists, it will be passed the following 1 parameter address:

  • A 256 byte area containing the fully qualified name of the workstation file that is about to be deleted

You may write your own user exit in COBOL if you desire. The name of the program must be MFMONPDL.

IDENTIFICATION DIVISION.
PROGRAM-ID. MFMONPDL.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.    IBM-PC.
OBJECT-COMPUTER.    IBM-PC.
DATA DIVISION.
LINKAGE SECTION.
01 P-WORKSTATION    PIC X(256).
PROCEDURE DIVISION USING P-WORKSTATION.
*> EXECUTE CODE HERE
   GOBACK.
Note: Note:

If you do not want the workstation file to be deleted, ensure that MFMONPDL sets this 256 byte area to an empty string before it exits.

Parent topic: Error Message Output


User exit after a workstation delete

If the ALLOW WORKSTATION DELETES option is on, a user exit is called and if it exists, it will be passed the following 1 parameter address:

  • A 256 byte area containing the fully qualified name of the workstation file that was deleted

You may write your own user exit in COBOL if you desire. The name of the program must be MFMONDEL.

IDENTIFICATION DIVISION.
PROGRAM-ID. MFMONDEL.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.    IBM-PC.
OBJECT-COMPUTER.    IBM-PC.
DATA DIVISION.
LINKAGE SECTION.
01 P-WORKSTATION    PIC X(256).
PROCEDURE DIVISION USING P-WORKSTATION.
*> EXECUTE CODE HERE
   GOBACK.
Parent topic: Error Message Output


User exit after all synchronization has been done

After each successful logical synchronization (downloads and uploads) has been performed, and prior to the monitor going to sleep until the next wakeup time, a user exit is called if it exists which will be passed 1 parameter address:

  • A 1 byte area containing the value X'00' if no uploads or downloads were done this cycle, X'01' if only uploads were done this cycle, X'02' if only downloads were done this cycle, or X'03' if both uploads and downloads were done this cycle

You may write your own user exit in COBOL if you desire. The name of the program must be MFMONSYN.

IDENTIFICATION DIVISION.
PROGRAM-ID. MFMONSYN.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.    IBM-PC.
OBJECT-COMPUTER.    IBM-PC.
DATA DIVISION.
LINKAGE SECTION.
01 P-FLAG PIC X(1).
PROCEDURE DIVISION USING P-FLAG.
*> EXECUTE CODE HERE
   GOBACK.
Parent topic: Error Message Output


SourceConnect: Mapping a PC Drive to Mainframe Data

You can use SourceConnect to map a PC drive to a mainframe dataset or catalog filter. You can then access mainframe files and resources from a PC, or from applications running on a PC.

  • About SourceConnect
  • Controlling the Location of Files
  • Protecting Mainframe Files from Being Overwritten
  • Security
  • Configuring SourceConnect
Parent topic: Using Enterprise Server with a Mainframe


About SourceConnect

Use SourceConnect to define mainframe datasets so that they appear to Micro Focus applications as normal workstation drives and directory structures.

All mainframe source type datasets, such as PDS, Librarian and Panvalet datasets, are available through SourceConnect. SourceConnect automatically filters out other datasets, such as sequential datasets, VSAMs, and PDS datasets that are of record format 'U'.

SourceConnect provides data integrity and a secure environment when correctly configured with your mainframe/workstation. Security is maintained through the standard mainframe System Authorization Facility (SAF), such as RACF, ACF/2 or Top Secret. Data integrity is supported through the SourceConnect interfaces with the mainframe.

By using SourceConnect, you can leave your source files on the mainframe, and dynamically access them using Micro Focus tools that are enabled for SourceConnect.

Parent topic: SourceConnect: Mapping a PC Drive to Mainframe Data


Controlling the Location of Files

When using SourceConnect to access source files on a mainframe, there will be files you want SourceConnect to read from and write to on the mainframe, but also files that you want to keep locally. SourceConnect uses mechanisms to enable you to control which files are based on the mainframe and which are workstation based.

When you edit your configuration to specify the mainframe files you want to be able to use, one of the entries you add is extensions. A file on the workstation with an extension specified in an extensions entry will be accessible on the mainframe as appropriate.

To decide whether or not a file is to be accessible on the mainframe:

  • SourceConnect first checks the drive the file is on. If the drive is logically specified in a drive entry in the configuration, the next process is to check the extension of the file.
  • If the file's extension is specified by an extensions entry (or specified by the extensions parameter of a Panvalet, PDS or Librarian system entry), the file is read from or written to the mainframe.
  • If the extension is not specified in the configuration file, or is not line sequential, it is read from or written to the current working directory instead, preserving the existing files on the mainframe.
Parent topic: SourceConnect: Mapping a PC Drive to Mainframe Data


Protecting Mainframe Files from Being Overwritten

When working on a mainframe, it is common practice to read a member from one dataset, edit it, then save it to a different dataset, avoiding the overwriting of the original member. Use the if-writing-to, or dataset update redirection entry in the configuration to avoid overwriting.

The entries take two parameters:

  • The first parameter defines a protected dataset.
  • The second defines the alternate dataset to be written to when attempting to write to the protected dataset.

SourceConnect prevents the first dataset from being over-written by performing all write operations transparently to the second dataset. Subsequent reads check this alternate dataset first before checking the protected dataset. If the member is found in the alternate dataset, then it is read from there.

A typical example of this would be to read files from a production dataset, and save edited versions of the files to a testing dataset.

Parent topic: SourceConnect: Mapping a PC Drive to Mainframe Data


Security

When you access a mainframe using SourceConnect, you are prompted for a user-id and password when needed. To avoid this prompt, SourceConnect can make use of MFDaemon to store the user-id and password. This information is stored in memory, and you can configure it to write to an INI file. This information is then available from the daemon whenever needed. When the PC is re-booted or the MFDAEMON CLOSE command is executed, MFDaemon reads the information from the INI file. Security must be turned on at all times.

Parent topic: SourceConnect: Mapping a PC Drive to Mainframe Data
Related concepts
About MFDaemon


Configuring SourceConnect

You use the Server Access Configuration dialog box to configure SourceConnect.

Accessing MFA Server Cfg

To display the Server Access Configuration dialog box, use one of the following options:

  • From the Windows Start menu, click Start > All Programs > Micro Focus Enterprise Developer > Configuration > Mainframe Access Configuration.
  • From the Compare and Synchronization Monitor main screen, on the Options menu, select Mainframe Access Configuration.

The Server Access Configuration dialog box appears.

  • Configure Mainframe Drives
Parent topic: SourceConnect: Mapping a PC Drive to Mainframe Data


Configure Mainframe Drives

You define a PC drive letter for use within tools supporting SourceConnect technology. The drive letter you define is mapped to a mainframe catalog search value.

To configure a mainframe drive:

  1. On the Server Access Configuration dialog box, select the SourceConnect tab.
  2. Click Add to display the drive mapping dialog box.
    Note: You need to have specified a mainframe node, see Adding a Mainframe Node for more information.
  3. On the drive mapping dialog box:, select a drive letter and enter the mainframe details to map to it.
    • Select the drive letter to map from the pull-down list. Only available drives are displayed.
    • In the Mainframe catalog search criteria field, enter a search string with wildcards that will find the catalogs that you want.
    • In the Node field, use the pull-down list to select a mainframe node that you have defined.
  4. Click OK to set your definitions.

    Each drive letter is associated with a specific node. This allows you to alter the node details without having to change the drive letter details.

    SourceConnect tab

By selecting the type mainframe you are required to enter the catalog search criteria for that logical SourceConnect drive. The drive letter gives you access to the entire mainframe, subject to standard mainframe security rules, however, in a workstation directory list against the logical SourceConnect drive, only datasets that match the criteria will be displayed.

You can specify multiple search criteria, delimited by semi-colons, in this field. All datasets that match any of these criteria will be accessible.

Note: It is not recommended to enter search criteria that produces a large result. SourceConnect is limited to about 1300 returned entries for a catalog search, and for each one mapped to a drive, the VTOC information must be obtained. This can result in a performance problem for large-size results.

For example, if you defined drive S: with the catalog search criteria of CSI01.JPD;MFI01.LAS, then all datasets that start with either CSI01.JPD or MFI01.LAS will be displayed in a workstation directory list when S:\*.* is used.

You can use an asterisk in the middle or end of the search criteria as well. For example CSI01.*.COBOL will give all datasets that begin with CSI01 and end with COBOL.

You can map multiple drive letters onto various mainframes to enable you to perform default directory searches on multiple catalog-search prefixes. This means you can access more than one catalog-search environment as different drive letters. This is only necessary when you want to see a different directory list of mainframe datasets when drive-letter :\*.* is referenced.

  • Configure Partitioned Datasets
  • Configure Migrated Partitioned Datasets
  • Configure Librarian Datasets
  • Configure Controlled Extensions
  • Configure Global Extension Overrides
  • Configure Dataset Update Redirections
Parent topic: Configuring SourceConnect
Related concepts
Configuring the Cache
Related information
Adding a Mainframe Node
Configure PVCS Drives


Configure Partitioned Datasets

To access this feature, click Configure your datasets on the SourceConnect tab.

This option defines a named dataset as being a PDS.

It is not recommended to use this entry, as all non-migrated PDS datasets are automatically picked up by SourceConnect, based on the catalog search criteria for the logical drive. By default, the associated extension for the dataset is the last qualifier in the dataset name. You can globally override all datasets with a specific last qualifier to a specific workstation extension by using the configure global extension overrides item bar.

The only reasons to use this configure partitioned dataset item bar, would be if the dataset could be migrated or, if you wished to override the specific associated workstation extension for this partitioned dataset, without affecting the override for other partitioned datasets with the same last qualifier, as all of these entries are automatically added to the directory search function, then you may have additional datasets that do not match the search criteria appearing in the list.

Dataset Configuration Partitioned tab

Dataset
Specify the name of the partitioned dataset.
Extension
Specify the extension that members of this dataset are to be associated with.

Any extensions specified here are automatically added to the configure controlled extensions list.

Parent topic: Configure Mainframe Drives
Related information
Configure Migrated Partitioned Datasets
Configure Librarian Datasets
Configure Controlled Extensions
Configure Global Extension Overrides
Configure Dataset Update Redirections


Configure Migrated Partitioned Datasets

If your PDSs can be migrated, then SourceConnect is unable to determine the dataset type, based on the VTOC information, as this does not exist while a dataset is migrated. If you wish for SourceConnect to "see" these datasets as well, then you must explicitly add them to the configure partitioned datasets list.

Parent topic: Configure Mainframe Drives
Related information
Configure Partitioned Datasets
Configure Librarian Datasets
Configure Controlled Extensions
Configure Global Extension Overrides
Configure Dataset Update Redirections


Configure Librarian Datasets

To access this feature, click Configure your datasets on the SourceConnect tab.

Defines a named dataset as being a Librarian dataset.

By default, the associated extension for the dataset is the last qualifier in the dataset name. You can globally override all datasets with a specific last qualifier to a specific workstation extension by using the configure global extension overrides item bar. With Librarian, multiple extensions are possible as Librarian keeps information about the member type in its database. You can specify that these various types be associated with various workstation extensions. All of these entries are automatically added to the directory search function, then you may have additional datasets that do not match the search criteria appearing in the list.

Dataset Configuration Librarian tab

Dataset
Specify the name of the Librarian dataset.
Default extension
The default may be specified for any members that do not match the specific extensions listed in the override list.
Extension override list
Specify the type/extension mapping that members of this dataset are to be associated with.

Any extensions specified here are automatically added to the configure controlled extensions list.

Parent topic: Configure Mainframe Drives
Related information
Configure Partitioned Datasets
Configure Migrated Partitioned Datasets
Configure Controlled Extensions
Configure Global Extension Overrides
Configure Dataset Update Redirections


Configure Panvalet Datasets

To access this feature, click Configure your datasets on the SourceConnect tab.

Defines a named dataset as being a Panvalet dataset.

By default, the associated extension for the dataset is the last qualifier in the dataset name. You can globally override all datasets with a specific last qualifier to a specific workstation extension by using the configure global extension overrides item bar. With Panvalet, multiple extensions are possible as Panvalet keeps information about the member type in its database. You can specify that these various types be associated with various workstation extensions. All of these entries are automatically added to the directory search function, then you may have additional datasets that do not match the search criteria appearing in the list.

Dataset Configuration Panvalet tab

Dataset
Specify the name of the Panvalet dataset.
Default extension
The default may be specified for any members that do not match the specific extensions listed in the override list.
Extension override list
Specify the type/extension mapping that members of this dataset are to be associated with.

Any extensions specified here are automatically added to the configure controlled extensions list.


Configure Controlled Extensions

To access this feature, click Configure your datasets on the SourceConnect tab.

This is one of the most important configuration parameters for SourceConnect. You will need to understand this statement, to be able to define and control mainframe files as SourceConnected files. This defines controlled extensions for input/output requests on the drive letters specified in the drive entries. Any file with an extension not in the list specified by this entry, or be in the default list, is written to the current working directory instead of to the relevant dataset on the mainframe. If an extension was defined in the partitioned dataset, Librarian dataset or Panvalet dataset, it does not have to be added here as well. This is done for you by SourceConnect.

Dataset Configuration Extensions tab

Extension to control
Specify the file extension that you want SourceConnect to control when accessing SourceConnect controlled drives. If the extension you are working with is not defined here, in the configure global extension overrides list, or in the default list supplied by SourceConnect, then SourceConnect will not try to access the file on the mainframe, but instead re-direct the request to the current working directory.

Use this entry to define which files Micro Focus tools can input/output to the mainframe. Do not include work files (such as .INT, .GNT, and .LST files) created by these tools in the list.

The following extensions are used by default:

ASSEM, ASSEMBLE, ASM, BMS, C, CBL, CIC, CNTL, CLIST, COB, COBOL, CONTROL, COP, COPY, COPYLIB, CPP, CPY, CSD, CTL, CTRL, DBD, DCT, DYL, ECL, FCT, GEN, H, INC, INCL, INCLUDE, JCL, JOB, LNK, MAC, MACLIB, MFS, MLC, PCT, PGM, PLI, PPT, PRC, PROC, PROCLIB, PSB, RCT, SCH, SRC, SOURCE, TSO, TXT, TEXT

There are a number of extensions you must not specify. These are as follows:

CSI, DLL, DLW, GDY, GNT, EXE, IDY, INT, LIST, LST, OBJ

Files with these extensions are always written to the current working directory. If you specified any of these extensions, a message is output when SourceConnect initializes.

Parent topic: Configure Mainframe Drives
Related information
Configure Partitioned Datasets
Configure Migrated Partitioned Datasets
Configure Librarian Datasets
Configure Global Extension Overrides
Configure Dataset Update Redirections


Configure Global Extension Overrides

To access this feature, click Configure your datasets on the SourceConnect tab.

This is one of the most important configuration parameters for SourceConnect. You will need to understand this statement, to be able to define and control mainframe files as SourceConnected files. This defines controlled extensions for input/output requests on the drive letters specified in the drive entries, with changes in the mainframe type to this specific extension. You may globally override mainframe types to be specific extensions with this statement. This is very useful, as it prevents you from having to code a partitioned dataset, Librarian dataset or Panvalet dataset statement for each dataset that you wish to override the extension with. For example, if you wanted to override all mainframe types of SOURCE to be CBL, then specify SOURCE as the mainframe type, and CBL as the associated workstation extension. You can add multiple override parameters.

Dataset Configuration Extensions Override tab

Mainframe type to override
Specify the mainframe type that you want SourceConnect to convert to the workstation extension.
Associated workstation extension
Specify the file extension that you want SourceConnect to use and control when accessing SourceConnect controlled drives for the mainframe type specified.
Parent topic: Configure Mainframe Drives
Related information
Configure Partitioned Datasets
Configure Migrated Partitioned Datasets
Configure Librarian Datasets
Configure Controlled Extensions
Configure Dataset Update Redirections


Configure Dataset Update Redirections

To access this feature, click Configure your datasets on the SourceConnect tab.

Forces all writes or rewrites to a specified dataset to be made to an alternative dataset, preserving the original. Additionally, the alternate dataset is checked first when doing a read of a member. A typical use for this entry is to ensure that source files are read from a production dataset, but any updated files are written to a separate, test dataset to avoid overwriting the existing files.

Dataset Configuration Redirections tab

When writing to dataset
Specify the name of the protected, typically production, dataset. This can be a partitioned dataset, Librarian dataset or Panvalet dataset.
Redirect to dataset
Specify the name of the unprotected, typically development, dataset. This can be a partitioned dataset, Librarian dataset or Panvalet dataset.
Parent topic: Configure Mainframe Drives
Related information
Configure Partitioned Datasets
Configure Migrated Partitioned Datasets
Configure Librarian Datasets
Configure Controlled Extensions
Configure Global Extension Overrides


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
Parent topic: Micro Focus Enterprise Server 2.3 Update 1 for Windows


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.
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 Enterprise Server 2.3 Update 1 for Windows


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.
For run-time system errors, ErrorCode is generally of the form COBRTnnnn.
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

  • COBRT064 Incompatible file locking mode (Recoverable)
    A process has attempted to open the file using a different locking mode than the one that is already in place.
  • 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


COBRT064 Incompatible file locking mode (Recoverable)

A process has attempted to open the file using a different locking mode than the one that is already in place.

The locking mode is determined by the tunable strict_file_locking. All processes accessing the same file need to be using the same locking mode (that is, all have the tunable set to the same value).

Parent topic: 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.

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


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.

One possible cause is when an attempt has been made to access the record area, but it has not yet been allocated because a file is not yet in the OPEN state; see the HOSTFD directive for more details.

In a Windows environment, this results in the file mfdebug.log being generated in your current directory. However, if the application does not have write permissions to that directory, mfdebug.log is created in a product specific directory instead, under the directory specified by the LOCALAPPDATA environment variable; for example, %LOCALAPPDATA%\Micro Focus\<product name>\<product version>\logs\mfdebug.log.

SupportLine may request you supply this file when troubleshooting the error.

Parent topic: COBRT101 - COBRT120


COBRT115 Unexpected signal (Fatal)

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

In a Windows environment, this results in the file mfdebug.log being generated in your current directory. However, if the application does not have write permissions to that directory, mfdebug.log is created in a product specific directory instead, under the directory specified by the LOCALAPPDATA environment variable; for example, %LOCALAPPDATA%\Micro Focus\<product name>\<product version>\logs\mfdebug.log.

SupportLine may request you supply this file when troubleshooting the error.

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().
  • COBRT128 Connection to Fileshare Server refused
    Your request to the Fileshare Server has been rejected, either because the server has been suspended, or your request was not valid at this time.
  • COBRT129 Attempt to access record zero of relative file (Recoverable)
    The value specified in the RELATIVE KEY data item contains the value zero.
  • COBRT130 Connection to Fileshare Server re-established (Recoverable)
    A connection to your Fileshare server has been re-established.
  • 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


COBRT128 Connection to Fileshare Server refused

Your request to the Fileshare Server has been rejected, either because the server has been suspended, or your request was not valid at this time.

You should investigate the state of your Fileshare server before continuing.

Note: You will receive this message if you attempt to connect directly to a server that is operating as a secondary server within a high availability group.
Parent topic: COBRT121 - COBRT140
Related concepts
Configuring iFileshare for High Availability
FSView


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


COBRT130 Connection to Fileshare Server re-established (Recoverable)

A connection to your Fileshare server has been re-established.

If there were any in-flight transactions at the point of the Fileshare server going down, these will have been rolled back.

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.

If you want the event to appear in the Windows Application Event log you can configure the Consolidated Tracing Facility to do this with configuration entries such as the following:

mftrace.dest = WINEVENT
mftrace.level = WARN

mftrace.emitter.winevent#level = 2
mftrace.comp.mf.rts#api = TRUE

The mftrace.emitter.winevent#level = 2 entry is required because by default the WINEVENT emitter does not output any events below level 3 (ERROR).

In previous versions of this COBOL system, the error returned by the system call was written to the Windows Application Event log. You can revert to this behavior by setting the os_error_log tunable to true. If you set os_error_log to true and configure the Consolidated Tracing Facility as described above, each COBRT199 error causes two entries to be written to the Windows Application Event log.

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.

One possible cause is when an attempt has been made to access the record area, but it has not yet been allocated because a file is not yet in the OPEN state; see the HOSTFD directive for more details.

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

  • COBRT221 Internal sort error (Fatal)
  • 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


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: 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.

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

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


COBRT241 Cannot instantiate an abstract class (Fatal)

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

Resolution:

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

Parent topic: COBRT241 - COBRT260


COBRT242 Could not resolve DoesNotUnderstand message (Fatal)

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

Resolution:

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

Parent topic: COBRT241 - COBRT260


COBRT243 Class could not be loaded (Fatal)

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

Resolution:

Check the definition of the class.

Parent topic: COBRT241 - COBRT260


COBRT244 Licensing initialization error (Fatal)

An error occurred initializing the run-time license.

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

Resolution

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

Parent topic: COBRT241 - COBRT260


COBRT245 There are no valid product licenses (Fatal)

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

Resolution

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

Parent topic: COBRT241 - COBRT260


COBRT246 Maximum number of product licenses exceeded (Fatal)

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

Resolution

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

Parent topic: COBRT241 - COBRT260


COBRT247 Licensing error (Fatal)

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

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

Resolution

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

Parent topic: COBRT241 - COBRT260


COBRT249 Process killed (signal-number) (Fatal)

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

Resolution:

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

Parent topic: COBRT241 - COBRT260


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

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

Resolution:

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

Parent topic: COBRT241 - COBRT260


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

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

Resolution:

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

Parent topic: COBRT241 - COBRT260


COBRT252 Memory corruption detected (Fatal)

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

Resolution:

You need to isolate the actual point in execution where the memory corruption occurs to 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


Data Access

  • Database Access
  • MBDT Configuration Utility
    Describes the options you can set for Mainframe Batch Database Tools (MDBTs).
  • Data Files
  • File Handling
Parent topic: Micro Focus Enterprise Server 2.3 Update 1 for Windows


Database Access

Enterprise Server provides several options to accommodate database access from your runtime applications.

  • HCO for DB2 LUW
  • HCO for SQL Server (HCOSS)
  • OpenESQL
Parent topic: Data Access


HCO for DB2 LUW

  • HCO Tools
  • How to
  • Command Line reference
Parent topic: Database Access


HCO Tools

Included in Host Compatibility Option are tools to:

  • Create databases with EBCDIC collating sequences
  • Process SQL DDL statements so that DB2 table definitions stored on the mainframe can be downloaded to the PC and used to create tables without having to be modified
  • Generate copybooks for tables (DCLGEN)
  • Export data in a variety of formats
  • Import data in a variety of formats
  • Bind or rebind packages

These tools are available from the HCO for DB2 LUW user interface, and the command line. See To start HCO tools and Command Line reference for details.

Before you start, be sure you have installed the prerequisite software. For more information, see Additional Software Requirements.

Note: You can use IBM's DB2 Control Center and/or the DB2 Setup tool to perform other HCO functions such as cataloging databases and servers, executing SQL, and generating aliases.
  • Create Database Tool
  • DDL Processor
  • DCLGEN
  • Export Data Tool
  • Import Data Tool
  • BindAll Packages Tool
Parent topic: HCO for DB2 LUW
Related concepts
Additional Software Requirements
Related tasks
To start HCO tools
Related reference
Command Line reference


Create Database Tool

Databases created on PCs or database servers store data in ANSI. To use these databases with EBCDIC-enabled subsystems such as IMS and CICS, you must have a database created with an alternate collating sequence.

You can run the Create Database tool from the HCO for DB2 LUW user interface, or using the mfhco create command.

Note: If you use any of the IBM tools to create the database, all data will be returned to your application in ANSI collating sequence. IBM does provide some examples of how to create databases with alternate collating sequences but the EBCDIC to ANSI translation that IBM uses may be different from the translation used in this COBOL development system. Therefore it is very important that you use the Create Database tool to create the database.
Parent topic: HCO Tools


DDL Processor

The DDL Processor processes SQL DDL statements using one of the following methods:
  • Transforming DB2 for z/OS syntax DDL statements to DB2 LUW format
  • Processing the DDL statements unchanged

You can run the DDL Processor from the HCO for DB2 LUW user interface, or using the mfhco ddl command.

Downloading Source DDL

DDL source files on the mainframe should be downloaded and converted to standard ANSI text files. The maximum input length per record accepted by the DDL processor is 80 bytes.

Note: If non-blank characters exist in columns 73 through 80, you must change maximum column to process to be 72 or they are treated as part of the DDL source statement. See mfhco ddl command for more details.

Downloading Data to Load Tables

There are two tools in Host Compatibility Option to help you load test data exported from tables located on the mainframe:

  • The Export Data tool
  • The Import Data tool

Using the DDL Processor to Load Data

You can also use the DDL processor to load or update data into tables by placing one or more of the following DML statements in the same file as DDL statements:

  • INSERT
  • UPDATE
  • DELETE
  • COMMIT

This is a convenient way to load test data into tables.

Statements cannot contain any host variables and you cannot use quotes ( " ) around literals. You must use apostrophes ( ' ). You should also issue a COMMIT before you try to insert data into a table if it was created within the same unit of work. For example:

-- Create Available Product table
 CREATE TABLE MF.PRODUCT
  (PROD_ID  CHAR(04)    NOT NULL
  ,PROD_DESC  CHAR(40)    NOT NULL WITH DEFAULT
  ,VERSION  CHAR(6)    NOT NULL WITH DEFAULT
  ,PRIMARY KEY (PROD_ID) )
  IN DSB8G210.CISC0001
 ;
 COMMIT
 ;

 -- Sample data for Product table

 INSERT INTO MF.PRODUCT (PROD_ID ,PROD_DESC ,VERSION )
 VALUES ('SR02' ,'Host Compatibility Option ' ,'2.0.01' )
Parent topic: HCO Tools


DCLGEN

Host Compatibility Option provides a tool to generate DDL for existing SQL tables or copybooks for tables in COBOL, PL/I or C syntax.

You can run the DCLGEN tool from the HCO for DB2 LUW user interface, or using the mfhco dclgen command.

Use Case Scenarios

Scenario 1
This example creates the file ITEMS.CPY from table DEMO.ITEMS in database DB2DEMO and prefixes all COBOL field names with the table name.

The DECLARE TABLE part of copybook file would look something like this:

************************************************************
*  MFHCODCL OPTIONS:
*  DATABASE : DB2DEMO
*  SCHEMA : DEMO
*  PREFIX : TABLE NAME
************************************************************
  EXEC SQL DECLARE DEMO.ITEMS TABLE
  ( ORD_NO    INTEGER   NOT NULL
  ,ITEM_NO    SMALLINT  NOT NULL
  ,PROD_ID    CHAR(4)
  ,QTY_ORDERED   SMALLINT  NOT NULL WITH DEFAULT
  ,QTY_SHIPPED   SMALLINT  NOT NULL WITH DEFAULT
  ,AMT_EACH    DECIMAL(7, 2) NOT NULL WITH DEFAULT
  ,DATE_ENTERED   TIMESTAMP  NOT NULL WITH DEFAULT
  ,DATE_SHIPPED   DATE
  ,ITEM_NOTES   VARCHAR(560)
  ) END-EXEC.

The COBOL DECLARATION part of copybook file would look something like this:

************************************************************
* COBOL DECLARATION FOR TABLE DEMO.ITEMS
************************************************************
 01 DCLITEMS.
  10 ITEMS-ORD-NO           PIC S9(09) COMP.
  10 ITEMS-ITEM-NO          PIC S9(04) COMP.
  10 ITEMS-PROD-ID          PIC X(4).
  10 ITEMS-QTY-ORDERED      PIC S9(04) COMP.
  10 ITEMS-QTY-SHIPPED      PIC S9(04) COMP.
  10 ITEMS-AMT-EACH         PIC S9(05)v9(02) COMP-3.
  10 ITEMS-DATE-ENTERED     PIC X(26).
  10 ITEMS-DATE-SHIPPED     PIC X(10).
  10 ITEMS-ITEM-NOTES.
   49 ITEMS-ITEM-NOTES-LEN  PIC S9(04) COMP.
   49 ITEMS-ITEM-NOTES-TEXT PIC X(560).
************************************************************
* COBOL INDICATOR VARIABLES FOR TABLE
************************************************************
 01 DCLITEMS-NULL.
  10 ITEMS-PROD-ID-NULL      PIC S9(04) COMP.
  10 ITEMS-DATE-SHIPPED-NULL PIC S9(04) COMP.
  10 ITEMS-ITEM-NOTES-NULL   PIC S9(04)COMP.
************************************************************
* THE NUMBER OF COLUMNS DESCRIBED BY THIS DECLARATION IS 9
************************************************************
Scenario 2
In this example, change the prefix to a user value of "HV" instead of using the table name as prefix and generate indicator values with a suffix of IND.

The COBOL DECLARATION part of copybook file would look something like this:

************************************************************
* COBOL DECLARATION FOR TABLE DEMO.ITEMS
************************************************************
 01 DCLITEMS.
  10 HV-ORD-NO           PIC S9(09) COMP.
  10 HV-ITEM-NO          PIC S9(04) COMP.
  10 HV-PROD-ID          PIC X(4).
  10 HV-QTY-ORDERED      PIC S9(04) COMP.
  10 HV-QTY-SHIPPED      PIC S9(04) COMP.
  10 HV-AMT-EACH         PIC S9(05)v9(02) COMP-3.
  10 HV-DATE-ENTERED     PIC X(26).
  10 HV-DATE-SHIPPED     PIC X(10).
  10 HV-ITEM-NOTES.
   49 HV-ITEM-NOTES-LEN  PIC S9(04) COMP.
   49 HV-ITEM-NOTES-TEXT PIC X(560).
************************************************************
* COBOL INDICATOR VARIABLES FOR TABLE
************************************************************
 01 DCLITEMS-IND.
  10 HV-PROD-ID-IND      PIC S9(04) COMP.
  10 HV-DATE-SHIPPED-IND PIC S9(04) COMP.
  10 HV-ITEM-NOTES-IND   PIC S9(04) COMP.
************************************************************
* THE NUMBER OF COLUMNS DESCRIBED BY THIS DECLARATION IS 9
************************************************************
Scenario 3
In this example, change the prefix to a user value of "FIELD" and generate numbered fields instead of column names. Use configuration default instead of specifying CBL for language.

The COBOL DECLARATION part of copybook file would look something like this:

************************************************************
* COBOL DECLARATION FOR TABLE DEMO.ITEMS
************************************************************
 01 DCLITEMS.
  10 FIELD-001       PIC S9(09) COMP.
  10 FIELD-002       PIC S9(04) COMP.
  10 FIELD-003       PIC X(4).
  10 FIELD-004       PIC S9(04) COMP.
  10 FIELD-005       PIC S9(04) COMP.
  10 FIELD-006       PIC S9(05)v9(02) COMP-3.
  10 FIELD-007       PIC X(26).
  10 FIELD-008       PIC X(10).
  10 FIELD-009.
   49 FIELD-009-LEN  PIC S9(04) COMP.
   49 FIELD-009-TEXT PIC X(560).
************************************************************
* COBOL INDICATOR VARIABLES FOR TABLE
************************************************************
 01 DCLITEMS-NULL.
  10 FIELD-003-NULL PIC S9(04) COMP.
  10 FIELD-008-NULL PIC S9(04) COMP.
  10 FIELD-009-NULL PIC S9(04) COMP.
************************************************************
* THE NUMBER OF COLUMNS DESCRIBED BY THIS DECLARATION IS 9
************************************************************
Scenario 4
In this example, create the file ITEMS.PLI from table DEMO.ITEMS in database DB2DEMO and prefix all field names with the table name. Language is PL/I.

The DECLARE TABLE part of copybook file would look something like this:

/*-------------------------------------------------------*/
/*  MFHCODCL OPTIONS:                                    */
/*   DATABASE : DB2DEMO                                  */
/*   SCHEMA : DEMO                                       */
/*   PREFIX : TABLE NAME                                 */
/*-------------------------------------------------------*/
 EXEC SQL DECLARE DEMO.ITEMS TABLE
 ( ORD_NO    INTEGER   NOT NULL,
  ITEM_NO    SMALLINT  NOT NULL,
  PROD_ID    CHAR(4),
  QTY_ORDERED   SMALLINT  NOT NULL WITH DEFAULT,
  QTY_SHIPPED   SMALLINT  NOT NULL WITH DEFAULT,
  AMT_EACH    DECIMAL(7, 2) NOT NULL WITH DEFAULT,
  DATE_ENTERED   TIMESTAMP  NOT NULL WITH DEFAULT,
  DATE_SHIPPED DATE,  ITEM_NOTES   VARCHAR(560)
 );

The PL/I DECLARATION part of copybook file would look something like this:

/*-------------------------------------------------------*/
/*  PL/I DECLARATION FOR TABLE DEMO.ITEMS                */
/*-------------------------------------------------------*/
DECLARE
1 DCLITEMS,
 5 ITEMS_ORD_NO     BIN FIXED(31),
 5 ITEMS_ITEM_NO    BIN FIXED(15),
 5 ITEMS_PROD_ID     CHAR(4),
 5 ITEMS_QTY_ORDERED    BIN FIXED(15),
 5 ITEMS_QTY_SHIPPED    BIN FIXED(15),
 5 ITEMS_AMT_EACH     DEC FIXED(5,2),
 5 ITEMS_DATE_ENTERED    CHAR(26),
 5 ITEMS_DATE_SHIPPED    CHAR(10),
 5 ITEMS_ITEM_NOTES    CHAR(560) VAR;
/*-------------------------------------------------------*/
/*  PL/I INDICATOR VARIABLES FOR TABLE                   */
/*-------------------------------------------------------*/
DECLARE 1 DCLITEMS_NULL,
 5 ITEMS_PROD_ID_NULL    BIN FIXED(15),
 5 ITEMS_DATE_SHIPPED_NULL   BIN FIXED(15),
 5 ITEMS_ITEM_NOTES_NULL   BIN FIXED(15);
/*-------------------------------------------------------*/
/*  THE NO. OF COLUMNS DESCRIBED BY THIS DECLARATION IS 9*/
/*-------------------------------------------------------*/
Scenario 5
This example creates the file ITEMS.C from table DEMO.ITEMS in database DB2DEMO and prefixes all field names with the table name. Language is C.

The copybook file would look something like this:

/*-------------------------------------------------------*/
/*  MFHCODCL OPTIONS:                                    */
/*   DATABASE : DB2DEMO                                  */
/*   SCHEMA : DEMO                                       */
/*   PREFIX : TABLE NAME                                 */
/*  C HOST VARIABLES FOR TABLE DEMO.ITEMS                */
/*-------------------------------------------------------*/
EXEC SQL BEGIN DECLARE SECTION;
struct dclitems
{
 long   items_ord_no;
 short   items_item_no;
 char   items_prod_id[4];
 short   items_qty_ordered;
 short   items_qty_shipped;
 double  items_amt_each;
 char   items_date_entered[26];
 char   items_date_shipped[10];
 struct {
    short len
    char data[560];
   }  items_item_notes;
/*-------------------------------------------------------*/
/*   C INDICATOR VARIABLES FOR TABLE                     */
/*-------------------------------------------------------*/
 short   items_prod_id_null;
 short   items_date_shipped_null;
 short   items_item_notes_null;
 };
EXEC SQL END DECLARE SECTION;
/*-------------------------------------------------------*/
/*  THE NO. OF COLUMNS DESCRIBED BY THIS DECLARATION IS 9*/
/*-------------------------------------------------------*/
Parent topic: HCO Tools


Export Data Tool

Once you have created SQL tables, you need data to test your applications. You may also need to distribute data to other PCs or to send data back to the mainframe. IBM and other vendors provide products to do this. However, if you have not installed one of these products, moving data around can be a problem.

Host Compatibility Option supplies you with an Export Data tool that you can combine with DB2 Connect, IBM's DRDA gateway, giving you a relatively inexpensive way of moving data between mainframe databases and PCs .

You can run the Export Data tool from the HCO for DB2 LUW user interface, or using the mfhco export command.

The Export Data tool has the following limitations:

  • All columns and rows in a table are exported. There is no ability in this tool to limit the data or rows exported.
  • Export formats WSF (Lotus worksheet) and IXF (mainframe) are not supported
  • IXF and DEL files are exported using IBM's EXPORT application programming interface. Some options of the API are not supported. See IBM's DB2 LUW Command Reference for list of all available options.
  • DSNTIAUL is exported using a SELECT statement, so large tables may take a while to process
  • LOB data types are not supported in DSNTIAUL format
  • LOB data types are generated as part of file in IXF and DEL formats. See IBM's DB2 LUW Command Reference for other limitations.

If you need to restrict rows and/or columns exported, you can use the IBM command line processor, DB2, or the IBM Control Center to export data. See IBM's DB2 LUW Command Reference for more details on how to use the IBM Control Center.

Parent topic: HCO Tools


Import Data Tool

The Import Data tool is designed for programmers who need sample data for testing. This tool is not intended to be used to load large quantities of data. If you want to load large quantities of data, you should contact IBM or other third-party vendors who provide a number of products that can handle this better than Host Compatibility Option. You should take care in using this tool to ensure that the database does not become unusable. You should back up your data regularly to provide a means of recovering from loss of data.

You can run the Export Data tool from the HCO for DB2 LUW user interface, or using the mfhco export command.

The Import Data tool has the following limitations:

  • Data for all columns in a table must be in import file. There is no ability in this tool to limit the column data being inserted.
  • Import formats WSF (Lotus worksheet) and IXF (mainframe) are not supported.
  • IXF and DEL files are imported using IBM's IMPORT application programming interface. Some options of the API are not supported. See IBM's DB2 LUW Command Reference for list of all available options.
  • DSNTIAUL files are converted to ANSI delimited format and then use the DEL IMPORT API.
  • LOB data types are not supported in DSNTIAUL format.
  • LOB data types generated as part of file in IXF and DEL formats. See IBM's DB2 LUW Command Reference for other limitations.
  • An LOB must be 32K or smaller, and the information contained in it must be in the same file as other data being imported.
Parent topic: HCO Tools


BindAll Packages Tool

Bind or rebind all packages (.bnd files) found in the current directory using the bind options specified.

You can run the BindAll Packages tool using the mfhco bindall command.

The BindAll Packages tool can bind using only these options:

  • Collection ID
  • Qualifier
  • Datetime
  • Isolation level
  • Row blocking
  • SqlWarn

To bind or rebind with any other options, use the IBM BIND command. See your IBM documentation for details.

Parent topic: HCO Tools


How to

  • To start HCO tools
  • To create a database
  • To process SQL DDL statements
  • To create a DCLGEN
  • To import data
  • To export data
  • To set HCO for DB2 LUW options
Parent topic: HCO for DB2 LUW


To start HCO tools

  • From your desktop, click Start > All Programs > Micro Focus Enterprise Server> Data Tools > HCO for DB2 LUW.
    Note: On Windows 8, Windows 10, and Windows Server 2012, you use the Start screen to invoke programs.
Parent topic: How to
Related concepts
HCO Tools
Related reference
Command Line reference


To create a database

  1. From the HCO for DB2 LUW interface, click Create Database.
  2. On the Create Database tab, complete the fields. See the Create Database tab topic for a description of each field.
  3. Click Run tool.
  4. Optionally, click the Log tab to view results.
Parent topic: How to


To process SQL DDL statements

  1. From the HCO for DB2 LUW interface, click DDL Processor.
  2. On the DDL Tool tab, complete the fields. See the DDL Tool tab topic for a description of each field.
  3. Click Run tool.
  4. Optionally, click the Log tab to view results.
Parent topic: How to


To create a DCLGEN

  1. From the HCO for DB2 LUW interface, click DCLGEN.
  2. On the DCLGEN tab, use the Table/Schema grid to select the tables and schemas you want to include in the generated copybook.
  3. Complete the remaining fields. See the DCLGEN tab topic for a description of each field.
  4. If not already connected to the specified database, click Connect.
  5. Click Run tool.
  6. Click the Copybook tab to see the generated copybook source.
Parent topic: How to


To import data

  1. From the HCO for DB2 LUW interface, click Import Data.
  2. On the Import tab, use the Table/Schema grid to select the tables and schemas you want to import.
  3. Complete the remaining fields. See the Import tab topic for a description of each field.
  4. If not already connected to the specified database, click Connect.
  5. Click Run tool.
  6. Optionally, click the Log tab to view results.
Parent topic: How to


To export data

  1. From the HCO for DB2 LUW interface, click Export Data.
  2. On the Export tab, use the Table/Schema grid to select the tables and schemas you want to export.
  3. Complete the remaining fields. See the Export tab topic for a description of each field.
  4. If not already connected to the specified database, click Connect.
  5. Click Run tool.
  6. Optionally, click the Log tab to view results.
Parent topic: How to


To set HCO for DB2 LUW options

  1. From the HCO for DB2 LUW interface, click Options.
  2. Using the grid, modify options as required. See the HCO for DB2 LUW Options topic for a description of each.
  3. Click Update to save changes.
Parent topic: How to


Command Line reference

  • mfhco create command
  • mfhco ddl command
  • mfhco dclgen command
  • mfhco import command
  • mfhco export command
  • mfhco bindall command
Parent topic: HCO for DB2 LUW
Related concepts
HCO Tools
Related tasks
To start HCO tools


mfhco create command

Syntax

mfhco create db=databasename [coll=collsequence] [log=logfilename]
   [drv=driveletter] [id=logon-id] [pass=password] [srvr=nodename] [lctn={L | R}]

Syntax Rules

  1. At least one space must occur before each parameter in the command.
  2. There must be an equals sign (=) between parameters and their values.
  3. If you omit parameters that have a default value, Host Compatibility Option uses the default value.

Parameters

databasename | Specifies the name of the new database.
collsequence | Specifies the collating sequence to use. The default value is MFD, which is the EBCDIC collating sequence installed by Enterprise Developer.
logfilename | The name of the logfile to capture output information. The default value is createdb.log.
driveletter | The drive letter to create local database on.
logon-id | The logon ID required to connect to the server where the database is to reside.
password | The password required to connect to the server where the database is to reside.
nodename | For databases on a remote server, the cataloged DB2 node name for that server.
L | Indicates that the database location is a local server. Default.
R | Indicates that the database location is a remote server.

Example

The following command:
mfhco create db=test drv=e
creates a database named test on drive e using the default Enterprise Server EBCDIC collating sequence.
Parent topic: Command Line reference


mfhco ddl command

Syntax

mfhco ddl db=databasename file=file [log=logfile]
    [max=colno] [mod=modify] [saveddl=savefile]

Syntax Rules

  1. At least one space must occur before each parameter in the command.
  2. There must be an equal sign (=) between parameters and their values.
  3. If you omit parameters that have a default value, Host Compatibility Option uses the default value.

Parameters

ddl | Specifies use of the DDL Processor. This parameter is positional.
databasename | Name of the database that you want to process DDL statements against.
file | The name of the file that contains DDL statements.
logfile | The name of log file to write processing details to. If this parameter is not specified, a logfile is created with a default logfile name using the project name. If you specify this parameter but specify no value for it (blank), this turns logging off.
colno | Column number to process DDL statements to. Must be a number less than or equal to 80.
modify | Set this parameter to "Y" if you want DDL statements converted to DB2 LUW format. Set this parameter to "N" if you want to process DDL statements unchanged. If you select this option, you must set the DDL delimiter value in the configuration file.
saveddl | Save the converted DDL to a file instead of writing it to the database.
savefile | The name of a file in which to save the converted DDL. In this case, the database is not updated.

Example

mfhco ddl db=db2demo file=hcosetup.sql log=ddlproc.log
Parent topic: Command Line reference


mfhco dclgen command

Syntax

mfhco dclgen db=databasename lang=language tbl=schemaname.tablename
  file=copybookname [pre={USER | TBL | NO}] [user=username] [fld={COL | NUM}]

Syntax Rules

  1. At least one space must occur before each parameter in the command.
  2. There must be an equal sign (=) between parameters and their values.
  3. If you omit parameters that have a default value, Host Compatibility Option uses the default value.

Parameters

databasename | Database to connect to.
language | Language to generate. cbl is the default; can also specify c or pli.
schemaname | Schema name for the generated copybook.
tablename | Table name for the generated copybook.
filename | Name of the copybook file to generate.
TBL | Specifies that the copybook prefix is the same as the table name. Default.
USER | Specifies that the prefix is supplied by the user.
NO | Specifies that there is no prefix.
username | A text string composed of valid COBOL characters, used as a prefix for each host variable in the copybook.
COL | Specifies the column name. Default.
NUM | Specifies the column number.

Example

mfhco dclgen db=db2demo lang=cbl tbl=demo.items file=item.cpy
Parent topic: Command Line reference


mfhco import command

Syntax

mfhco import db=databasename tbl=tablename file=filename [fmt=format]
    [log=logfile] [chardel=chardelimiter] [coldel=coldelimiter]
        [date=dateformat] [plus=sign] [savedel=delfilename]
            [commit=rowcount]

Syntax Rules

  1. At least one space must occur before each parameter in the command.
  2. There must be an equal sign (=) between parameters and their values.
  3. If you omit parameters that have a default value, Host Compatibility Option uses the default value.

Parameters

import | Invokes the Import Data command-line processor. This parameter is positional.
databasename | Name of the database to import to.
tablename | Name of table to be imported. You can specify both the schema and the table name, separated with a period.
filename | Filename to import data from.
format | Format to import data. Valid values are IXF, DEL, and DSNTIAUL. You can use DSN for DSNTIAUL.
logfile | File to write processing messages to. If this parameter is not specified, a logfile is created in the current directory. In Windows environments, the default logfile name is based on the project name. .
chardelimiter | Delimiter used to enclose character data when import format is DEL specified. Default is double quotes (").
coldelimiter | Delimiter used to indicate the end of column data when import format DEL is specified. Default is comma (,).
dateformat | Format to import date fields in if importing data in DSNTIAUL or DEL format. Default is the format for your country. Valid values for DSNTIAUL are ISO, USA, EUR, and JIS. ISO is only valid option for DEL format.
sign | Generate positive numeric data with plus signs when importing data in DEL format. Valid values are "Y" for yes to generate plus signs or "N" to not generate plus signs. Default is "Y".
savedel | Save DSNTIAUL as an ASCII-delimited file that can be used to import large amounts of data via a third-party tool.
delfilename | Filename of the ASCII-delimited file.
rowcount | The number of rows per commit.

Comments

The Import Data tool can also be run as a batch function.

Example

mfhco import db=db2demo fmt=dsn tbl=demo.product file=product.dsn chardel=' log=import.log commit=1000
Parent topic: Command Line reference


mfhco export command

Syntax

mfhco export db=databasename tbl=table file=filename
    [fmt=format] [log=logfile] [chardel=chardelimiter] [coldel=coldelimiter]
       [date=dateformat] [plus=sign]

Syntax Rules

  1. At least one space must occur before each parameter in the command.
  2. There must be an equal sign (=) between parameters and their values.
  3. If you omit parameters that have a default value, Host Compatibility Option uses the default value.

Parameters

export | Parameter to invoke Export Data command line processor. Parameter is positional.
databasename | Name of the database to connect to.
table | Name of table to be exported. Can include both schema and table name.
filename | Filename to export data to.
format | Format in which to export data. Valid values are IXF, DEL, and DSNTIAUL. You can use DSN for DSNTIAUL.
logfile | File to write processing messages to. If this parameter is not specified, a logfile is created with a default logfile name using the project name.
chardelimiter | Delimiter used to enclose character data when export format DEL specified. Default is double quotes (").
coldelimiter | Delimiter used to indicate the end of column data when export format DEL is specified. Default is comma (,).
dateformat | Format to export date fields in if exporting data in DSNTIAUL or DEL format. Default is format for your country. Valid values for DSNTIAUL are ISO, USA, EUR and JIS. ISO is the only valid option for DEL format.
sign | Generate positive numeric data with plus signs when exporting data in DEL format. Valid values are "Y" for yes to generate plus signs or "N" to not generate plus signs. Default is "Y".

Comments

You can also run the Export Data tool as a batch function.

Example

mfhco export db=db2demo fmt=ixf file=product.ixf tbl=demo.product log=export.log
Parent topic: Command Line reference


mfhco bindall command

Syntax

mfhco bindall db=databasename [qualifier=schema] [collection=collection-id]
    [datetime=format] [isolation=isolation-level] [blocking=row-blocking]
       [sqlwarn=compile-option] [id=logon-id] [pass=password]

Parameters

bindall | Parameter to invoke BindAll command line processor. Parameter is positional.
databasename | Name of the database to connect to.
schema | Name of the schema to use for table qualification.
collection-id | A 128-byte collection identifier for the package.
format One of the following datetime formats to return when executing the application:
  • USA
  • ISO
  • JIS
  • EUR
  • LOC
  • DEF
isolation-level Determines how far a program bound to this package can be isolated from the effect of other executing programs. Valid values are:
  • CS
  • RR
  • RS
  • UR
row-blocking The type of row blocking for cursors. Valid values are:
  • UNAMBIG
  • ALL
  • NO

The blocking of row data that contains references to LOB column data types is also supported in partitioned database environments.

compile-option Indicates whether warnings are returned from the compilation of dynamic SQL statements via PREPARE or EXECUTE IMMEDIATE, or from describe processing via PREPARE...INTO or DESCRIBE. Valid values are:
  • YES
  • NO
logon-id | Logon ID required to connect to the server where the database resides.
password | Password required to connect to the server where the database resides.

Comments

You must execute the BindAll Packages tool either from a command prompt in the directory that contains your .bnd files, or from your project as a post-build event. For more information on build events, see .

The BindAll Packages tool generates a log file, bindall.txt, that summarizes the results for all packages bound. Individual results are written to programName.txt.

Log files are written to the current directory.

Example

mfhco bindall db=db2demo qualifier=DEMO datetime=usa isolation=cs sqlwarn=no
Parent topic: Command Line reference


HCO for SQL Server (HCOSS)

HCO for SQL Server (HCOSS) provides tools for migrating DB2 databases and applications to SQL Server databases and applications. It is a superset of OpenESQL; therefore applications that use HCOSS have access to all OpenESQL functionality.

For third-party software requirements, see the Database Access Support and DB2 Database Migration Process topics.

  • HCOSS Toolset
  • Using HCOSS with Windows User Account Control (UAC)
  • Managing Connections
  • Migrating Databases
  • Migrating Applications
  • Deploying Native Applications
  • Managing Log Files
  • How to
  • Reference
Parent topic: Database Access
Related concepts
DB2 Database Migration Process


HCOSS Toolset

The HCOSS toolset includes:

Manage Connections Tool
Enables you to connect to both your mainframe's DB2 database and a SQL Server database running locally or remotely on a local area network.
Database Migration Tools
Extract Schema
Downloads the DB2 database schema objects and creates an XML schema file representing the schema structure.
Assess Data Migration
Produces an editable report of the information in your extracted schema.
Define Lists
Reads the XML schema file created using the Extract Schema tool and enables you to create a list of database objects to transfer to the SQL Server database.
Generate DDL
Reads both the XML schema file and the list of selected database objects and translates the information into a SQL Server DDL script.
Transfer Data
Builds and executes an SSIS package to move each specified database object to your SQL Server database.
Compare Data
Verifies the validity of newly imported data by comparing it with the original data.
Application Migration Tools
Assess Application Migration
Analyzes the EXEC SQL statements in your DB2 program and copybook code and flags statements that could potentially cause problems when migrating to SQL Server in different migration scenarios, with and without using HCOSS.
Manage Packages and Plans
Create and edit scripts that enable you to bind DBRM members, packages, and plans to your COBOL programs, and to free packages and plans.
Generate SPD File
Enables you to generate stored procedure definition (SPD) files from extracted DB2 schema. You can use a generated SPD file to generate a COBOL wrapper.
Application Database support
HCOSS also provides SQL Server functions and meta-data tables to support mainframe emulation in a SQL Server database. For more information, see Application Database Support.
Customization Tools
Customize Type Mappings
View or change the default type mappings for your SQL database.
Customize SQLCode Mappings
View or change the default OpenESQL SQLCodes and their DB2 SQLCode and DB2 SQLState equivalents that are stored in your SQL database.
Parent topic: HCO for SQL Server (HCOSS)
Related concepts
Manage Connections Tool
Migrating Databases
Migrating Applications
Why You Should Use the Assess Application Migration Tool
Application Database Support
Related tasks
To start HCO for SQL Server
To set HCOSS options
Related reference
Options


Using HCOSS with Windows User Account Control (UAC)

Restriction: This topic applies to the Windows Vista and 7 operating systems and later. It does not apply to the Windows XP operating system.

When you have enabled the Windows User Account Control (UAC) feature, HCOSS exhibits different behavior depending on whether or not you are logged in as a standard user or an administrator, whether or not you are a member of the Windows Administrators group, and how you start the HCOSS user interface.

Standard user and administrator modes

You can run HCOSS as a standard user or as an administrator. When you run as an administrator, all HCOSS features are available to you. However, when you run HCOSS as a standard user, some features are limited. We recommend that you run HCOSS as an administrator when possible.

HCOSS UAC behavior

When using UAC, HCOSS runs in either standard user or administrator mode, depending on these three factors:
  • The Windows group to which you belong - standard user or administrator
  • How you start HCOSS - from the Start menu or from within the IDE
  • The settings for HCOSS UAC Behavior options

To run HCOSS in standard user mode

The following scenarios show how to run HCOSS in standard user mode, limiting access to some features. In each scenario, the statement in each first-level bullet point must be true. Assume all HCOSS UAC Behavior options are set to their defaults:
Scenario 1
  • You are logged into Windows as a standard user
  • You are not part of the Administrator group
  • You start HCOSS as a standard user using either of the following methods:
    • From within the IDE by selecting
    • From the Start menu
Scenario 2
  • You are logged into Windows as a standard user
  • You are also part of the Windows Administrator group
  • You start HCOSS using either of the following methods:
    • From within the IDE by selecting
    • From the Start menu, answering No to any subsequent prompts.
Scenario 3
  • You are logged into Windows as an administrator
  • You start HCOSS from the Start menu, answering No to any subsequent prompts

To run HCOSS in administrator mode

The following scenarios show how to run HCOSS in administrator mode, providing full access to all features. In each scenario, the statement in each first-level bullet point must be true:
Scenario 1
  • You are logged into Windows as a standard user
  • You are a member of the Windows Administrator group
  • You start HCOSS using either of the following methods:
    • From the Start menu, answering Yes to any subsequent prompts
    • From the Start menu but right-clicking HCO for SQL Server and selecting Run as administrator
Scenario 2
  • You are logged into Windows as an administrator
  • You start HCOSS using any of the following methods:
    • From within the IDE by selecting
    • From the Start menu
    • From the Start menu by right-clicking HCO for SQL Server and selecting Run as administrator

HCOSS UAC prompts

By default, HCOSS could prompt you at startup depending on the settings of the HCOSS UAC Behavior options. You might encounter one or both of the following prompts:
Relaunch HOCSS as Administrator
This prompt appears by default when:
  • You are a member of the Administrator group
  • You launch HCOSS from the Start menu without selecting Run as administrator

If you respond Yes to this prompt, HCOSS relaunches in administrator mode, and Windows displays the User Account Control dialog box. Respond to this prompt as appropriate.

If you respond No to this prompt, HCOSS resumes launching in standard user mode.

If you check Stop asking me, HCOSS changes the default setting of the Prompt to automatically run as Administrator option from True to False.

Running as non-administrator information
When you are running HCOSS in standard user mode and you are not a member of the Administrators group, this dialog box appears to notify you that some features are limited in standard user mode.

If you check Do not tell me again, HCOSS changes the default setting of the Warn non-Administrator users of limited functionality option from True to False.

Note: You can change the default HCOSS behavior with regard to launching HCOSS with UAC and UAC prompts by setting the options manually. For information on setting HCOSS UAC Behavior options, see Options.
Parent topic: HCO for SQL Server (HCOSS)
Related tasks
To start HCO for SQL Server
To set HCOSS options
Related reference
Options


Managing Connections

To successfully migrate DB2 databases and applications to SQL Server, you must establish a connection to both databases. You can do this using the Manage Connections tool, or a combination of other connection utilities.

For ODBC connectivity, HCOSS supports SQL Server Native Client 10.0 and 11.0, including the ODBC Driver 11 for SQL Server. We recommend that you always use the most recent version of this driver available when creating new connections. We also recommend that you upgrade existing connections to use the most recent driver when possible. HCOSS detects the ODBC driver version at startup, when creating, editing, and repairing SQL Server system or user connection types, and provides the option to upgrade where appropriate.

  • Manage Connections Tool
  • Connection Types
  • Advanced Connection Options
Parent topic: HCO for SQL Server (HCOSS)


Manage Connections Tool

The Manage Connections tool enables you to make the SQL Server and DB2 connections needed to run your applications.

It includes the following key functionality:

  • Creates ADO.NET connections to your mainframe DB2 database.
  • Maintains a catalog of DSN connections, including the provider used to access the connection and the connection parameters used by the provider.
  • Automatically creates both ADO.NET and ODBC connections to SQL Server using one set of connection parameters.
  • Sets both 32-bit and 64-bit connections on 64-bit operating systems using one set of connection parameters.
  • Creates export XML files you can use to import connections into either the ADO.NET Connection Editor or the Manage Connections tool.
  • Provides the option to upgrade the ODBC driver where appropriate.
Note: The Manage Connections tool is not compatible with DB2 ODBC connections.
Parent topic: Managing Connections
Related concepts
HCOSS Toolset
Application Migration Process
Connection Types


Connection Types

HCOSS provides the System and User connection types. For each, connection information is tracked and stored in a series of files.

System Connection Type

The Manage Connections tool tracks and stores connection information in the following files:
%PROGRAMDATA%\Micro Focus\HCOSS\Connections\ConnectionTracking.hcocon
A work file containing tracking information.
%WINDOWS%\Microsoft.NET\Framework\v2.0.50727\CONFIG\machine.config
A configuration file that stores 32-bit framework 2.0, 3.0, and 3.5 (CLR 2) system connection strings.
%WINDOWS%\Microsoft.NET\Framework\v4.0.30319\Config\machine.config
A configuration file that stores 32-bit framework 4.0 (CLR 4) system connection strings.
%WINDOWS%\Microsoft.NET\Framework64\v2.0.50727\CONFIG\machine.config
A configuration file that stores 64-bit framework 2.0, 3.0, and 3.5 (CLR 2) system connection strings.
%WINDOWS%\Microsoft.NET\Framework64\v4.0.30319\Config\machine.config
A configuration file that stores 64-bit framework 4.0 (CLR 4) system connection strings.

User Connection Type

The Manage Connections tool tracks and stores connection information in the following files:
%LOCALAPPDATA%\Micro Focus\HCOSS\Connections\UserConnectionTracking.hcocon
A work file containing tracking information.
%LOCALAPPDATA%\Micro Focus\UserConnections32_v2.config
A configuration file that stores 32-bit framework 2.0, 3.0, and 3.5 (CLR 2) user connection strings.
%LOCALAPPDATA%\Micro Focus\UserConnections32_v4.config
A configuration file that stores 32-bit framework 4.0 (CLR 4) user connection strings.
%LOCALAPPDATA%\Micro Focus\UserConnections64_v2.config
A configuration file that stores 64-bit framework 2.0, 3.0, and 3.5 (CLR 2) user connection strings.
%LOCALAPPDATA%\Micro Focus\UserConnections64_v4.config
A configuration file that stores 64-bit framework 4.0 (CLR 4) user connection strings.
Parent topic: Managing Connections
Related concepts
Manage Connections Tool


Advanced Connection Options

For most applications, as an alternative to the Manage Connections tool, you can also establish appropriate connections using a combination of the Micro Focus ADO.NET Connection Editor and the Microsoft ODBC Data Source Administrator tool. This can be useful if you want to fine-tune your connection settings, including those that are set to defaults when you use the Manage Connections tool.

Restriction: CICS applications that use ADO.NET must use the HCOSS Manage Connections tool to catalog a connection. In this case, you cannot use the ADO.NET Connection Editor or the Microsoft ODBC Data Source Administrator tool.

If you choose to use the ADO.NET Connection Editor and Microsoft ODBC Data Source Administrator to create and catalog your connections, be aware that your development environment can affect your connections.

In 64-bit environments, Microsoft provides 32-bit and 64-bit versions of the ODBC Administrator tool. You might need to create 32- and 64-bit versions of some connections. Here are the scenarios and required connections necessary for using a connection with HCOSS tools:

Scenario | Required Connections
Using HCOSS application migration tools in a 32-bit environment, and targeting a 32-bit framework 2.0, 3.0, or 3.5 environment (x86) | 32-bit framework 2.0, 3.0, and 3.5 ADO.NET SQL Server, 32-bit framework 4.0 ADO.NET SQL Server, and 32-bit ODBC SQL Server
Using HCOSS application migration tools in a 64-bit environment, and targeting a 32-bit framework 2.0, 3.0, or 3.5 environment (x86) | 32-bit framework 2.0, 3.0, and 3.5 ADO.NET SQL Server, 32- and 64-bit framework 4.0 ADO.NET SQL Server, and 32-bit ODBC SQL Server
Using HCOSS application migration tools in a 64-bit environment, and targeting a 64-bit framework 2.0, 3.0, or 3.5 environment (x64) | 64-bit framework 2.0, 3.0, and 3.5 ADO.NET SQL Server, 32- and 64-bit framework 4.0 ADO.NET SQL Server, and 32- and 64-bit ODBC SQL Server
Using HCOSS application migration tools in a 32-bit environment, and targeting a 32-bit framework 4.0 environment (x86) | 32-bit framework 4.0 ADO.NET SQL Server and 32-bit ODBC SQL Server
Using HCOSS application migration tools in a 64-bit environment, and targeting a 64-bit framework 4.0 environment (x64) | 32- and 64-bit framework 4.0 ADO.NET SQL Server and 32- and 64-bit ODBC SQL Server

To specify a 32-bit or 64-bit connection, use the Settings > Availability menu in the ADO.NET Connection Editor, or the radio buttons provided on the Microsoft ODBC Data Source Administrator tool.

In 64-bit environments, if UAC is turned on, run the ADO.NET Connection Editor as an administrator.

Note: The ADO.NET Connection Editor and the ODBC Data Source Administrator are available from Start > All Programs > Micro Focus Enterprise Server > Data Tools > Data Connections.
Parent topic: Managing Connections


Migrating Databases

HCO for SQL Server (HCOSS) provides tools and methods for migrating DB2 databases from the mainframe to SQL Server databases on a Local Area Network.

Note: For information about prerequisite third-party software and supported DB2 versions, see the HCO for SQL Server (HCOSS) section in the topic Database Access Support with Native COBOL.
  • DB2 Database Migration Process
  • DB2 Temporary Table Migration
  • Extract Schema Tool
  • Assess Data Migration Tool
  • Define Lists Tool
  • Generate DDL Tool
  • Transfer Data Tool
  • Compare Data Tool
  • Mainframe Batch Database Tools
Parent topic: HCO for SQL Server (HCOSS)
Related concepts
HCOSS Toolset


DB2 Database Migration Process

Use the HCOSS standard tool set to migrate the DB2 databases from your mainframe to SQL Server databases that run on Windows.

The basic process is as follows:

  1. Install all prerequisite third-party software. For details, see Additional Software Requirements.
  2. Gather the information required to connect to mainframe DB2 using the Microsoft OLE DB provider Data Access Tool, which includes:
    • Mainframe logon credentials
    • Network address and port for your DB2 location
    • OLE DB provider parameters including initial catalog and collection
    Note: Your mainframe DBA must set mainframe permissions such that the Microsoft OLE DB provider can create packages in a mainframe collection. Users who connect to the mainframe when using HCOSS must have access to this collection.
  3. Run the Data Access Tool that comes with the OLE DB provider, and use it to:
    • Create the mainframe packages required by the provider
    • Create a new data source to connect to the mainframe
    • Test the connection
    • Create the packages used by the provider
    • Run the sample query
  4. Create a destination SQL Server database using Microsoft SQL Server SQL Server Management Studio.
  5. Create a connection to your SQL Server database using the Manage Connections tool.
  6. Extract the DB2 schemas from your mainframe DB2 database to a local or shared directory using the Extract Schema tool.
  7. Optionally assess the data migration by viewing and editing the information in the schema extract file created by the Extract Schema tool.
  8. Define a list of extracted DB2 schema objects that you want to migrate to the SQL Server database using the Define Lists tool.
  9. Create an SQL script to create the DB2 schema objects in the new SQL Server database using the Generate DDL tool.
  10. Populate the SQL Server database with the selected schema objects from the DB2 database using the Transfer Data tool.
  11. Verify the results of the transferred data using the Compare Data tool.
Parent topic: Migrating Databases
Related concepts
Extract Schema Tool
Define Lists Tool
Generate DDL Tool
Transfer Data Tool
Compare Data Tool
Deploying Native Applications
HCO for SQL Server (HCOSS)
Related reference
Required DB2 Catalog Tables


DB2 Temporary Table Migration

HCOSS supports the DECLARE GLOBAL TEMPORARY TABLE statement. When executed, HCOSS creates a SQL Server temporary table. HCOSS only supports use of the SESSION qualifier for global temporary tables, HCOSS does not support use of regular tables in the SESSION schema.

HCOSS does not support the direct migration of temporary tables created using the CREATE statement. However, you can accommodate this type of temporary table by converting the CREATE statement to a DECLARE statement, and adding it to the start of any program that references the table created by the converted CREATE statement. Use the following guidelines when adding a DECLARE statement to a program:
  • You must convert the application to use the SESSION schema as a qualifier for access to global temporary tables that were CREATEd on the mainframe
  • You can DECLARE a table multiple times; executing a DECLARE statement for a global temporary table that already exists has no effect
Once the DECLARE statements have been added to appropriate programs, HCOSS converts the tables as follows:
  • When DECLARE GLOBAL TEMPORARY TABLE is executed, HCOSS creates a temporary table.
  • Because SQL Server temporary table names always start with #, HCOSS generates a temporary table name using the original table name used in the mainframe code, plus a prepended # sign. For example, if the original table name is EMP, the SQL Server temporary table is named #EMP.
Parent topic: Migrating Databases


Extract Schema Tool

The HCOSS tools used to prepare for a migration rely on a data file known as a schema extract file. This file contains metadata extracted from the DB2 system catalog for database schemas you want to migrate. As the first step in preparing for a DB2 database to SQL Server database migration, use the Extract Schema tool to create this file. You can run the tool either from the HCOSS user interface, or from the command line using the MFExtractSchemaInfo command.

Schema Extraction Process

The Extract Schema tool is the only HCOSS tool that requires access to the mainframe before actual data migration begins. It extracts data for selected schemas from the following DB2 catalog tables in the SYSIBM schema:
Object Type DB2 System Catalog Tables

tables, aliases, synonyms, columns, sequences

  • SYSTABLES
  • SYSCOLUMNS
  • SYSSEQUENCES
  • SYSSYNONYMS

indexes

  • SYSINDEXES
  • SYSKEYS

routines, parameters

  • SYSROUTINES
  • SYSPARAMS

constraints (relational, check, key)

  • SYSCHECKS
  • SYSCHECKDEP
  • SYSCHECKS2
  • SYSCONSTDEP
  • SYSTABCONST
  • SYSKEYCOLUSE
  • SYSRELS
  • SYSFOREIGNKEYS
  • SYSSEQUENCESDEP

views

  • SYSVIEWS
  • SYSVIEWDEP
Note: The user ID and password combination you use to connect to your mainframe must grant you READ access to your DB2 system catalog tables. For a complete list of required tables, see the topic Required DB2 Catalog Tables.
The Extract Schema tool does the following to create the schema extract file:
  • Connects with the DB2 database
  • Requests a list of available schemas in the DB2 database
  • Populates the tool with the list of available schemas
  • Enables selection of specific schemas for migration
  • Enables selection of an estimated or actual table row count for each table in the schema
  • Generates an XML file containing a representation of the objects in the selected schemas, including:
    • Dependent objects such as dependent tables or views and tables referenced by a foreign key in a different table
    • Parameter values necessary to create the same schema objects in SQL Server 2008
  • Reports results

Modifying, Exporting, and Importing Schema Extract Files

Once you have created a schema extract file, you can use the Schema Extract tool to modify it, export it, and/or import it. The export and import features enable you to share schema extract files with multiple users, and to assist Micro Focus SupportLine in troubleshooting migration issues.

In addition, you can use a schema extract file to generate stored procedure definition (SPD) files that can then be used to generate COBOL wrapper programs for your DB2 stored procedures.

Security

We offer two methods of implementing security with regard to catalog and mainframe access during the Extract Schema process:

Catalog Security
When catalog security is a concern, consider creating an additional schema containing views of SYSIBM DB2 catalog tables. This enables the user of the Extract Schema tool to extract from the new schema, and therefore does not require query access to the catalog tables themselves. If catalog security is not a concern, then anyone who runs the Extract Schema tool requires query access to the required DB2 catalog tables in the SYSIBM schema.
Mainframe Security
If your aim is to limit mainframe access to a single individual or system, you can use the Export and Import features of the Schema Extract tool to provide additional staff access to schema extract files without granting access to the mainframe.

HCOSS uses the generated schema extract file in the next step of the database migration process - defining lists of specific tables and views to migrate.

Parent topic: Migrating Databases
Related concepts
DB2 Database Migration Process
Deploying Native Applications
Related tasks
To extract DB2 schemas
To modify a schema extract file
Related reference
MFExtractSchemaInfo command
Extract Schema Tool Log Files
Extract Schema Tool Error Messages
Required DB2 Catalog Tables
Schema Extract tab
Create New Schema Extract
Results tab


Assess Data Migration Tool

The Assess Data Migration tool enables you to examine extracted DB2 schemas to estimate the table sizes, and to identify the tables you want to migrate to your SQL Server database using HCOSS.

The Assess Data Migration Tool provides the following functionality:

  • Reads the content of an extracted schema file created using the Extract Schema tool.
  • Shows the contents of the extracted schema, including the following information for each table represented in the schema:
    • Creator
    • Name
    • Row count
    • Count type
    • Maximum row size
    • Data volume
    • Transfer option
    • Date of last update
  • Provides two count type options for each table:
    • Actual - Determined by running a query against the DB2 table on the mainframe. Depending on the table size, this could be time consuming; however, the results are reliably accurate.
    • Estimated - Based on the statistics collected by the DB2 RUNSTATS utility. While this is the most time-efficient method for determining table size, it is not always accurate because the statistics can be out of date.
    The default setting is based on the Table Row Count option you selected when extracting the schema.
  • Provides two data migration transfer options for each table represented in the extracted schema:
    • HCOSS - to migrate all data in the table
    • OTHER - to bypass migration of the data in the table
  • Updates the schema extract file with your changes.
  • Provides a report of error messages encountered when updating the schema extract file.
  • Enables you to save the extracted schema information as a flat text file or in CSV format compatible with spreadsheet software.
Parent topic: Migrating Databases


Define Lists Tool

Use the Define Lists tool to select specific tables and views with which to generate a list of objects to transfer to your SQL Server database. The Generate DDL tool uses this list to create SQL Server objects. You can run the tool either from the HCOSS user interface, or from the command line using the MFObjectList command.

The Define Lists tool includes the following functionality:
  • Reads the XML file generated by the Extract Schema tool
  • Provides a list of available objects
  • Enables selection of specific objects to transfer
  • Saves the transfer information to a file, enabling future editing of the list
    Note: You cannot change the source schema for an existing transfer list unless it is empty.

HCOSS uses the saved transfer information in the next step of the database migration process - generating DDL tasks to move the data.

Parent topic: Migrating Databases
Related concepts
DB2 Database Migration Process
Related tasks
To define an object transfer list
Related reference
MFObjectList command
Define Lists Tool Log Files
Define Lists Tool Error Messages
Transfer Lists tab
Create New List dialog box


Generate DDL Tool

Use the Generate DDL tool to create the DDL script used to migrate your DB2 schema objects to your SQL Server database. Each script you create is one DDL task. As with the other HCOSS tools, you name your DDL tasks and store them in a local or shared location.

You can run the Generate DDL tool either from the HCOSS user interface, or from the command line using the MFDDLConverter command.

To run the Generate DDL tool, you must have:
  • A schema extract file containing schema objects, created using the Extract Schema tool.
  • An object transfer list created using the Define Lists tool.
  • A connection to your production SQL Server database against which to execute your DDL scripts. Optional if you're using the tool only for the purpose of exporting a DDL script.
  • A connection to a test SQL Server database (optional).
The Generate DDL tool includes the following functionality:
  • Reads the schema extract file, filtered by the object transfer list that specifies the objects you want to migrate
  • Translates the database structure found in the extracted schema and transfer list, including schemas, tables, views, indexes, constraints, and relational information, into a SQL Server 2008 DDL script
  • Creates DDL script commands that drop and create objects, or restore missing objects in the SQL Server database
  • Maps DB2 data types to SQL Server 2008 data types
  • Creates tables using data type mappings defined in the Customize Type Mappings tool
  • Enables you to customize DDL at the object level
  • Enables you to edit schema mappings
  • Tests DDL task specifications against a test SQL Server data source
  • Executes generated DDL against your production SQL Server
  • Enables you to export the generated DDL as an SQL script
  • Reports results of DDL test runs and executions

HCOSS uses DDL tasks in the next step of the database migration process - transferring the data to the SQL database.

Note: HCOSS does not support XML indexes. Therefore, no XML indexes existing in the DB2 database are created in the DDL. Likewise, any column that is part of an index and is mapped to the SQL Server XML data type is not created. This is true even if the originating DB2 index and column are of XML type but are mapped to the XML data type.
Parent topic: Migrating Databases
Related concepts
DB2 Database Migration Process
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL
Related reference
MFDDLConverter command
Generate DDL Tool Log Files
Generate DDL Tool Error Messages
DDL Tasks tab
Create New DDL Task dialog box
Customize DDL tab
Schema Mappings tab
Results tab


Transfer Data Tool

Use the Transfer Data tool to build and execute an SSIS package for each table you want to migrate from the DB2 database to the SQL Server database. Each transfer you define is one Transfer Data task. You can run the Transfer Data tool either from the HCOSS user interface, or from the command line using the MFDataTransferCtlr command.

As with the other HCOSS tools, you name your data transfer tasks and store them in a local or a shared location.

To run the Transfer Data tool, you must have:
  • A connection to your DB2 database
  • An associated DDL task
  • A connection to your SQL Server database
The Transfer Data tool includes the following functionality:
  • Reads the DDL task you created with the Generate DDL tool
  • Builds one SSIS package for each table specified in the associated DDL task
  • Executes SSIS packages to transfer data for all tables defined in the associated DDL task
  • Enables you to customize your Transfer Data tasks from the DB2 database to the SQL Server database by providing specifications for handling logs, errors, triggers, constraints, and source table row counts, and including WHERE and/or ORDER BY clauses in SELECT statements.
    Note: Ensure that the required schema objects are in place in the destination SQL Server database before executing a data transfer task.
  • Enables you to export SSIS packages
  • Reports results

The Transfer Data tool automatically names and saves each SSIS package it builds, and stores them in the same local or shared location as the transfer data tasks. SSIS package files use the following naming convention:

tableName_RunTimePackage.dtsx.

  • SSIS Packages
  • Data Type Support
  • Data Transform Types
Parent topic: Migrating Databases
Related concepts
DB2 Database Migration Process
Related tasks
To transfer data
To customize a transfer data task
Related reference
MFDataTransferCtlr command
Transfer Data Tool Log Files
Transfer Data Tool Error Messages
Transfer Data Tasks tab
Create New Transfer Data Task dialog box
Customize Transfer Data tab
Results tab


SSIS Packages

HCOSS transfers data from DB2 databases to SQL Server 2008 databases by building one SQL Server Integration Services (SSIS) package for each of the database tables selected for transfer, and then executing these packages.

An SSIS package is a collection of SQL script commands. When you execute an SSIS package, the SSIS engine runs each script in sequence. We chose SSIS packages as the mechanism to transfer data because they are a flexible and efficient deployment option. You can schedule, script, customize, extend, and integrate SSIS packages using SQL Server and tools. SSIS packages can also be reused by the Execute Package Utility of SQL Server Integration Services, and it can be loaded into the SQL Server Business Intelligence Development Studio for debugging purposes.

For more information about SSIS packages, see the documentation for the Microsoft SQL Server Development Center, available on the Microsoft Web site.

Parent topic: Transfer Data Tool


Data Type Support

While most of the data types in DB2 are supported by the tool, there are a few exceptions.

Lack of support may be due to a delay between a new type being added to DB2 and support for the new type being added to provider APIs, or because SQL Server does not have a suitable type to map the new DB2 type to. For instance, DECFLOAT (16 byte float) and XML are among the new data types added to DB2 for z/OS v9.1. Because there is no corresponding 16 byte float data type in SQL Server 2008, both the Microsoft and IBM OLE DB Providers output it as 8 byte float, suffering from potential loss of precision.

The BLOB data type is not supported by the current version (2.0) of Microsoft OLE DB Provider for DB2. Check with Microsoft to see when this data type will be supported. For the XML data type, neither Microsoft OLE DB Provider for DB2 supports it nor does IBM OLE DB Provider, in their current versions. The IBM DB2 .NET Data Provider is a promising alternative to the OLE DB Providers for DB2, as it supports the XML data type. It will be incorporated in the tool in the future. However, its current version (v9.5.3) wrongly outputs DECFLOAT(p) as Numeric(p,0) with 0 scale, where p stands for the precision.

For SQL Server 2008, the SQL Server OLE DB/Native Client supports all the incoming data types.

Parent topic: Transfer Data Tool


Data Transform Types

There are two types of data transforms that may occur in the data transfer process. The first type is explicit from the point view of an SSIS package, the conversion between Unicode characters and non-Unicode characters. This conversion is automatically handled by the tool, which adds an SSIS Data Transform component to the package.

The second type is implicit, the conversion between subtypes of the same data type, such as conversion between DataTime and DataTime2, conversion between REAL and FLOAT. This type of conversion is handled internally by the SQL Server Database engine and there is no need to add a Data Transform component to the package.

Parent topic: Transfer Data Tool


Compare Data Tool

Use the Compare Data tool after transferring data to verify and compare the newly imported data with the original data. As with the other HCOSS tools, you create and name compare data tasks and store them in a local or shared location. You can run the Compare Data tool either from the HCOSS user interface, or from the command line using the MFTestConversion command.

To run the Compare Data tool, you must have:
  • A connection to your DB2 database
  • An associated DDL task
  • A connection to your SQL Server database
The Compare Data tool includes the following functionality:
  • Reads the data from the DB2 database source connection and the SQL Server database destination connection
  • Compares the data found in each
  • Shows the results for each row of data that was transferred from the source connection to the destination connection
Parent topic: Migrating Databases
Related concepts
DB2 Database Migration Process
Related tasks
To compare transferred data
To run customized data comparisons
Related reference
MFTestConversion command
Compare Data Tool Log Files
Compare Data Tool Error Messages
Compare Data Tasks tab
Create New Compare Data Task dialog box
Customize Compare Data tab
Results tab


Mainframe Batch Database Tools

Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability; however, this feature is not intended for production use and it is not supported as such. Furthermore, Micro Focus does not guarantee that this feature will be delivered at a GA level and if it is, then the functionality provided might differ considerably from this technology preview.

Enterprise Server provides a series of batch tools to assist you in migrating mainframe databases. See Mainframe Batch Database Tools (MBDT) for complete information.

Parent topic: Migrating Databases


Migrating Applications

HCO for SQL Server (HCOSS) provides tools and methods for migrating mainframe-based DB2 applications to Windows-based SQL Server applications.

  • Application Migration Process
  • Application Database Support
  • Binding Applications
  • Manage Packages and Plans Tool
  • DSN Bind Utility
  • Managing DBRMs
  • Running Applications
Parent topic: HCO for SQL Server (HCOSS)
Related concepts
HCOSS Toolset
Why You Should Use the Assess Application Migration Tool


Application Migration Process

Host Compatibility Option for SQL Server (HCOSS) and OpenESQL provides features and tools that assist in migration of mainframe applications that use DB2 to applications that run on Windows and use SQL Server. HCOSS also includes tools that enable you to migrate DB2 databases.

Note: All DB2 application components must reside either on your machine or on your local area network before beginning the migration to SQL Server.

You can use a combination of the following tools and features to achieve successful COBOL application migration, which includes building and binding an application:

HCOSS Assess Application Migration tool
Used to determine the best method of migration you can use to automatically convert your DB2 SQL code to SQL Server.
HCOSS Manage Connections tool
Used to create a connection to the SQL Server database.
HCOSS Manage Packages and Plans tool
Used to bind DBRM members into packages and plans, and to bind packages into plans. It also generates and saves BIND commands to bind script (.hcodsn) files you can execute using the DSN Bind utility.
DSN Bind utility
A free-standing Windows command-line utility used to achieve mainframe-like binding using a subset of the functionality of the mainframe DSN utility. This option is available if you do not create bind scripts that bind the application during the build process
HCOSS-specific OpenESQL SQL compiler directive options
Available in the Enterprise Developer product, these provide SQL syntax compatibility between DB2 and SQL and also provide binding functionality.

While you can choose from other methods of application migration using HCOSS, the basic and recommended process of COBOL and PL/I application migration includes:

  1. Using the HCOSS Manage Connections tool, connect to your SQL Server database.
  2. Using the Enterprise Developer product, create a project based on the COBOL Native Console Application template.
  3. Using the Assess Application Migration tool, determine the SQL conversion method that best fits your COBOL or PL/I source code.
  4. Take appropriate steps to convert your source code, based on your selected conversion method. This could include manually fixing your existing code based on the findings reported in the Assess Application Migration tool, or using HCOSS with or without the BIND option to convert the code.
  5. Add mainframe or converted COBOL or PL/I source code to the project in Enterprise Developer.
  6. Add appropriate SQL OpenESQL compiler directive options in the project properties.
  7. Also in the project properties, add a post-build event that runs the DSN command and binds the application to the SQL Server database.
  8. Build the application, automatically binding the application to the database.
  9. Run the application.
Parent topic: Migrating Applications
Related concepts
Running Applications
Binding Applications
Manage Connections Tool
Why You Should Use the Assess Application Migration Tool
Related tasks
To assess application migration


Application Database Support

HCOSS database migration tools transfer customer data from mainframe DB2 databases to SQL Server databases.

HCOSS also provides SQL Server functions and metadata tables that enable SQL Server databases to emulate DB2 mainframe behavior and facilities. This additional SQL Server support consists of:

  • Scalar SQL functions that emulate mainframe DB2 SQL
  • Metadata tables and SQL functions that emulate mainframe DB2 packages and plans

You can add HCOSS DB2 emulation support to a new or an existing SQL Database using Enterprise Developer. For complete information, see the Application Database Support topic in your Enterprise Developer documentation.

Parent topic: Migrating Applications
Related concepts
HCOSS Toolset
Binding Applications
DSN Bind Utility


Binding Applications

Once you have built your application such that it generates the necessary DBRMs, you must bind the DBRMs to your application by directly binding the DBRMs, or by binding the DBRMs into packages and/or plans that can be accessed by your run-time application.

You have several options for binding applications:
  • Use the Manage Packages and Plans tool to generate bind script files (.hcodsn files) containing BIND script commands that you can execute immediately to achieve application binding, or that you can save for later execution.
  • Use the Manage Packages and Plans tool to create and save bind script files to execute using the DSN Bind utility at a command prompt or as a post-build event.
  • Manually code bind script files to execute using the DSN Bind utility at a command prompt or as a post-build event.
    Note: For a listing of commands that are valid in HCOSS bind script files, see the topic Bind Script Commands.
  • Bind from JCL by coding DSN commands directly into the JCL.

Whether you bind your applications via the Manage Packages and Plans tool or directly with the DSN Bind utility, the results are the same. This is because the Manage Packages and Plans tool actually runs the DSN Bind utility for you when you execute a script command.

We recommend that you bind your applications by creating collections and packages from DBRM members and then binding those packages to one or more plans. This method offers a significant advantage over binding DBRM members directly into a plan. For example, if you need to change the SQL in a single source member, and that source member is bound into a package that has been bound into a plan, you only need to rebind the changed member to its package. However, if the changed member is bound directly into a plan, you must rebind the entire plan to include the change.

Parent topic: Migrating Applications
Related concepts
Manage Packages and Plans Tool
DSN Bind Utility
Local DBRMs
Managing DBRMs
Shared DBRMs and multi-user environments
Running Applications
Application Migration Process
Freeing Packages and Plans
Application Database Support
Related tasks
To create a bind script file
To open an existing bind script file
To create a new package
To create a new plan
To edit an existing BIND command
To execute one or all bind script lines
To free one or more packages
To free one plan or all plans
To bind from the command line
To manually code a bind script file
Related reference
Assessment Tasks tab
DSN command
Bind Script Commands


Manage Packages and Plans Tool

Use the Manage Packages and Plans tool to create and edit bind script files that contain BIND commands. You can execute these scripts from the Manage Packages and Plans tool, or save them to execute later with the tool or using the DSN Bind utility. The tool also enables you to free (clean out) old or unused packages and plans from your SQL Server database.

With regard to binding applications, the Manage Packages and Plans tool provides the following functionality:
  • Generates BIND commands according to specifications you provide.
    Note: You can also bind applications on your deployment server as well as your development server; however, to do this you must have appropriate permissions on the deployment server machine.
  • Saves the commands in bind script files (.hcodsn files) to any location you specify so that you can open, edit, and execute the commands again at any time.
  • Reports BIND command errors.
  • Executes one, some, or all of the BIND commands in your script file to either generate stored procedures that populate the SYSIBM schema or remove stored procedures that already exist in your SQL Server database.
With regard to freeing packages and plans, the Manage Packages and Plans tool provides the following functionality:
  • Free packages, removing associated system table data and associated stored procedure(s) from your SQL Server database
  • Free plans, removing associated system table data and associated stored procedure(s) from your SQL Server database, and removing package associations to the plan
  • Package Specifications
  • Plan Specifications
  • Freeing Packages and Plans
Parent topic: Migrating Applications
Related concepts
Manage Packages and Plans Tool
DSN Bind Utility
Binding Applications
Freeing Packages and Plans
Migration Scenarios
Deploying Native Applications
Related tasks
To create a bind script file
To open an existing bind script file
To create a new package
To create a new plan
To edit an existing BIND command
To execute one or all bind script lines
To free one or more packages
To free one plan or all plans
Related reference
Assessment Tasks tab
Bind Scripts tab
Bind Packages tab
Bind Plans tab
Free Packages tab
Free Plans tab


Package Specifications

You must provide the following specifications to the Manage Packages and Plans tool to enable it to generate a valid BIND PACKAGE script command:
Collection name
You can specify any name you choose, and add one or more packages to that collection. HCOSS creates the collection the first time you execute a package that you specify to be stored in the collection.
Library name
The name of a library containing extracted DBRMs.
  • DBRM libraries are located under localHCOSSFiles\DBRMDataSets, where localHCOSSFiles represents the value of the Local HCOSS Directory HCOSS option.
  • The Manage Packages and Plans tool provides you with a list of the available libraries from which to select.
  • Each library contains one DBRM for each source code member.
  • Each DBRM contains the extracted EXEC SQL statements from a single source member.
Member name
The name of the DBRM from which you want to create the package. This is the program ID of the source code member from which the DBRM was extracted. If there is more than one DBRM in the specified library, you can select from a list of available members.
Default qualifier
The name of a schema to use as the default qualifier for this package. (Optional)
Action
The action you want to take with regard to this package and the collection. If this package doesn't already exist in the collection, you can click Add to add it. If it does exist in the collection, you can click Replace to replace the current package version with an updated DBRM member, or you can replace a specific version by specifying the version identifier for the package that you want to replace and clicking Replace Version. HCOSS generates a new version for the package when you generate the DBRM.
Parent topic: Manage Packages and Plans Tool
Related tasks
To create a new package
To edit an existing BIND command
Related reference
Bind Packages tab


Plan Specifications

You must provide some or all of the following specifications to the Manage Packages and Plans tool to enable it to generate each BIND PLAN script command:
  • Plan name - You can specify any name you choose. HCOSS creates the plan the first time you bind it.
  • Default qualifier (optional) - the name of a schema to use as the default qualifier for this plan. HCOSS applies plan qualifiers to DBRM members specified in the plan; however, packages included in the plan use the qualifier specified for the package when it was executed, ignoring any specified plan qualifier.
  • Action - the action you want to take with regard to this plan. If the plan doesn't already exist, you can add it. If it does exist, you can replace it with modified specifications you provide.
  • Collections that contain packages you want to include in the plan.
  • Packages you want to include.
  • DBRM members you want to include in the plan.
  • DBRM libraries in which you want to search for specified DBRM members.
Parent topic: Manage Packages and Plans Tool
Related tasks
To create a new plan
To edit an existing BIND command
Related reference
Bind Plans tab


Freeing Packages and Plans

Over time, as a result of binding multiple DBRMs into multiple packages and plans, you might accumulate more data records and stored procedures in your SQL Server database than you need to run your application. In this case, you can use the Manage Packages and Plans tool to free (clean out) the packages and plans that you no longer need.

When you free a package, the Manage Packages and Plans tool removes associated system table data about the package and the stored procedure(s) associated with the package. You can remove all versions or a specific version of each package. You cannot restore a package that you have freed. Instead, you must bind the package again.

When you free a plan, the Manage Packages and Plans tool removes associated system table data about the plan and the stored procedure(s) associated with the plan. This includes removing all associations with packages bound into the plan. However, the packages themselves remain intact. Remember that a single package can be accessed individually and/or from any plan into which is has been bound. Therefore, even when you free a plan, its packages remain usable in those other contexts. If you want to also free the packages associated with a plan, you must free them separately.

You cannot restore a plan that you have freed. Instead, you must bind the plan again.

Parent topic: Manage Packages and Plans Tool
Related concepts
Binding Applications
Manage Packages and Plans Tool
Related tasks
To free one or more packages
To free one plan or all plans


DSN Bind Utility

Important: Starting with Enterprise Server 2.2 Update 1 and continuing with each subsequent release, run the DSN Bind utility against all of your existing SQL Server databases. This ensures that all mainframe artifacts stored in the database are updated appropriately with each software release.

Using the DSN Bind utility, you can bind your database to your SQL Server application from the command line

The DSN Bind utility requires that you have an active connection to your SQL Server database, and that you provide a bind script file (.hcodsn file) containing the DSN commands you want to execute. You can create the bind script file using the Manage Packages and Plans tool, or create it manually in a text editor.
Note: For a listing of commands that are valid in HCOSS bind script files, see the topic Bind Script Commands.

The DSN Bind utility executes in two sequential phases each time you run it - the Schema Update execution phase followed by the Bind Script execution phase.

Schema Update Execution

In this phase of execution, DSN checks the SQL Server database to which you are connected to ensure that the tables and stored procedures it requires are present in the database, and that the table and function definitions are consistent with the version of HCOSS in use. If the checks return successfully, DSN moves on to the Bind Script Execution phase. However, if the checks fail, DSN performs a schema update before moving on.

DSN database checks fail, triggering a schema update, only when either of the following is true:
  • You run DSN against a new SQL Server database
  • You run DSN for the first time after installing an HCOSS upgrade
  • DSN determines that necessary tables and/or stored procedures are missing from the database
To perform a schema update, DSN executes the following SQL scripts against your SQL Server database:
  • InstallSYSIBM.sql - creates metadata tables that DSN uses to manage bound DBRMs.
  • InstallBindProcs.sql - creates stored procedures that DSN uses to manage these tables.
  • InstallDigitsFunction.sql - creates the following functions to emulate DB2 functions not provided by SQL Server:
    • DATEINTERVAL
    • DIGITS
    • JULIANDAY
    • LASTDAY
    • LPAD
    • MIDNIGHT_SECONDS
    • NEXTDAY
    • RPAD
    • STRIP
    • TIMEINTERVAL
    • TRANSLATE
    • TRUNCATE

These SQL scripts reside in your %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss directory.

To ensure successful completion of the schema update process, connect to your SQL Server database using login credentials that include the following permissions:
  • CREATE SCHEMA
  • CREATE TABLE
  • DROP TABLE
  • CREATE INDEX
  • DROP INDEX
  • CREATE PROCEDURE in the SYSIBM schema
  • DROP and CREATE FUNCTION in the dbo schema
Important: This set of required permissions provides broader access to the SQL Server database than is necessary for the checking and binding done by DSN on a regular basis, that is, when database checks do not trigger the schema update process. If you routinely bind your applications by executing DSN from the command line, and you prefer to restrict permissions for day-to-day use, you can avoid possible errors and prevent DSN from triggering an automatic schema update by completing the process manually immediately after creating a new SQL Server database and after each HCOSS upgrade. To perform a manual schema update, connect to your SQL Server database using login credentials that grant the required permissions, and then run the SQL scripts manually.

Permissions required to run database checking are the same as those required for bind script execution.

Bind Script Execution

In the Bind Script Execution phase, DSN:
  • Generates stored procedures that bind packages and plans, maintaining them as metadata in the following SQL Server database tables:
    SYSIBM.SYSDBRM
SYSIBM.SYSPACKAGE
SYSIBM.SYSPACKLIST
SYSIBM.SYSPLAN
  • For each DBRM package specified in a BIND PACKAGE command, generates a separate stored procedure for each static SQL statement, saving them to your SQL Server database using the following naming convention:

    PKG:collectionName.memberName consistencyToken$statementNumber

    Where consistencyToken is a DSN-generated string that provides a unique name for the stored procedure, and statementNumber is a DSN-generated number starting at 0. For example:

    PKG:COLLECTION1.MEMBERAEEEcKIKy$0

  • For each plan specified in a BIND PLAN command, generates stored procedures for specified packages/members, saving them to your SQL Server database using a similar naming convention:

    PLN:planNameconsistencyToken$statementNumber

    For example:

    PLN:MYPLAN1.MEMBERAFFFdLJLz$0

To ensure successful completion of the Bind Script Execution phase, connect to your SQL Server database using login credentials that include the following permissions:
  • CREATE SCHEMA
  • CREATE PROCEDURE
  • EXECUTE PROCEDURE in the SYSIBM schema
Parent topic: Migrating Applications
Related concepts
Manage Packages and Plans Tool
Binding Applications
Local DBRMs
Managing DBRMs
Shared DBRMs and multi-user environments
Migration Scenarios
Application Database Support
Related tasks
To bind from the command line
To manually code a bind script file
Related reference
Assessment Tasks tab
DSN command
Bind Script Commands


Managing DBRMs

HCOSS manages DBRMs in DBRM libraries local to each user, and also in a shared DBRM library available to all HCOSS users. HCOSS ensures that each program and application is bound using DBRMs from the appropriate library.

  • Local DBRMs
    Explains how HCOSS manages local DBRMs.
  • Shared DBRMs and multi-user environments
    Explains how HCOSS ensures that the appropriate version of each DBRM is found and used when binding an application that is routinely accessed and maintained by more than one HCOSS user.
Parent topic: Migrating Applications
Related concepts
Shared DBRMs and multi-user environments
Binding Applications
DSN Bind Utility


Local DBRMs

DBRMs are stored in one of two places:
  • The DBRMDataSets\DBRMLIB subdirectory of the directory specified in your Local HCOSS Directory HCOSS option (default).
  • A subdirectory of the DBRMDataSets directory.

For a single program or application, binding is done on the local level using DBRMs available in the local DBRM libraries.

Note: When binding a program or application for which there are no local DBRMs, HCOSS uses DBRMs found in the shared DBRM library. See Shared DBRMs and Multi-User Environments for more information.
Parent topic: Managing DBRMs
Related concepts
Shared DBRMs and multi-user environments
Binding Applications
DSN Bind Utility


Shared DBRMs and multi-user environments

HCOSS maintains a DBRM library that is located in the DBRMDataSets subdirectory of the directory specified in your Shared HCOSS Directory HCOSS option. This shared DBRM library provides a single location for all production DBRMs, regardless of which user generated them. This shared DBRM library is essential for binding large applications accessed by multiple users.

Enterprise Server supports applications developed in Enterprise Developer. The best practices that ensure successful sharing of DBRMs in a multi-user environment apply to the application development phase. For complete information, see the Shared DBRMs and multi-user environments topic in your Enterprise Developer documentation.

Parent topic: Managing DBRMs
Related concepts
Shared DBRMs and multi-user environments
Binding Applications
DSN Bind Utility
Local DBRMs
Managing DBRMs


Running Applications

Your run-time applications require access to the DBRMs containing your SQL Server information. Therefore, you must specify the package collection or plan to which you have bound the DBRMs needed for a particular application.

Note: Because plan selection is specific to a connection, HCOSS maintains separate settings of CURRENT PACKAGE PATH, CURRENT PACKAGESET and APPLICATION PLAN for each connection used by an application.
  • CICS Applications - DBRM Specification
  • JCL Applications - DBRM Specification
Parent topic: Migrating Applications
Related concepts
Binding Applications
Application Migration Process


CICS Applications - DBRM Specification

CICS applications migrated using HCOSS and running under Enterprise Server require that you specify a package collection, list of package collections, or a plan in which your application's DBRMs are bound. You can do this one of two ways:

  • Enterprise Server environment variables

    Depending on how you have bound your DBRMs, set one the following environment variables in the Configuration Information field on the Enterprise Server Administration Server > Properties > General tab for the enterprise server running the application:

    • ES_DB_APPLICATION_PLAN
    • ES_DB_PACKAGESET
    • ES_DB_PACKAGE_PATH

    These variables set the APPLICATION PLAN, CURRENT PACKAGESET or CURRENT PACKAGE PATH special registers. By setting one of these variables, you create a global setting for a CICS region.

  • In application source code

    Add one of the following statements to your source code:

    • SET APPLICATION PLAN
    • SET CURRENT PACKAGESET
    • SET CURRENT PACKAGE PATH

    Use SET APPLICATION PLAN or SET CURRENT PACKAGESET to explicitly set the plan name or collection name containing your DBRMs. Use SET CURRENT PACKAGE PATH to specify a list of collections from which to select.

    Note: This method is less desirable because it requires changes to application code.
Parent topic: Running Applications


JCL Applications - DBRM Specification

JCL run-time applications migrated with HCOSS require that you specify the plan or package collection(s) to which its DBRMs are bound. This is accomplished using one of three methods:
  • Explicitly on the JCL RUN command
    JCL passes the PLAN parameter value from the JCL RUN command to OpenESQL, which then uses this value to set the plan used by the application. For example:
    RUN PROG(progName) PLAN(planName)
  • Automatically by default
    If you do not specify a PLAN parameter in the JCL RUN command, JCL defaults to using the program name as the plan name. For example:
    RUN PROG(progName)
  • In application source code

    This method overrides the automatic default method. It also enables you to specify package collection(s) instead of a plan. Add one of the following statements to your source code:

    • SET APPLICATION PLAN - Explicitly set the plan name
    • SET CURRENT PACKAGESET - Explicitly set the collection name
    • SET CURRENT PACKAGE PATH - Specify a path containing collections from which to select
Parent topic: Running Applications


Deploying Native Applications

The software components required for successful HCOSS application deployment depend on your deployment scenario. For details, see Additional Software Requirements.

Important: This topic assumes that all applications being deployed to Enterprise Server were developed and compiled using the Enterprise Developer product.

Deploy an Application Compiled Without DBRMLIB

To deploy an Enterprise Developer HCOSS application that was not compiled using the DBRMLIB directive, meaning that you did not bind the DBRM files for your application, complete the steps presented in the topic Deploying Native COBOL Applications. The steps presented there are necessary to successfully deploy your application to the deployment machine.

Development Machine
  • Build and test the HCOSS application with a development SQL Server machine.
Deployment Machine
  • Follow the steps defined in Deploying Native COBOL Applications, moving your HCOSS application as specified
  • Create a connection to the deployment SQL Server machine
  • Test the HCOSS application with the deployment SQL Server machine

Deploy an Application Compiled With DBRMLIB

To bind an Enterprise Developer HCOSS application using the DBRMLIB directive and deploy it to a deployment machine, you have two choices:

Bind the application from your development machine
Development Machine
  • Build and test the HCOSS application with a development SQL Server machine
  • Create a connection to the deployment SQL Server machine
  • Bind the HCOSS application to the deployment SQL Server machine using the connection you created
Deployment Machine

  • Follow the steps defined in Deploying Native COBOL Applications, moving your HCOSS application as specified

  • Create a connection to the deployment SQL Server machine
  • Test the HCOSS application with the deployment SQL Server machine
Bind the application from your deployment machine
Development Machine
  • Build and test the HCOSS application with a development SQL Server machine.
Deployment Machine
  1. Follow the steps defined in Deploying Native COBOL Applications.
  2. Be sure that all prerequisite software is installed on the machine. See Additional Software Requirements for details.
  3. Copy your HCOSS application from the development machine to the appropriate directory structure on the deployment machine.
    Important: You must create some or all of the required directory structure manually.

    Specifically, copy database request modules (DBRMs), that is, the DBRMName.hcodbrm files, from the development machine to the equivalent directory on the deployment machine. The location of your DBRM files varies on your development machine depending on your HCOSS options, and the specified DBRMLIB directive. The location on your development machine is:

    localHCOSSFiles\DBRMDataSets\DBRMLIBName

    Where localHCOSSFiles represents the value of the Local HCOSS Directory HCOSS option, and DBRMLIBName represents the value of the DBRMLIB directive.

    Note: If no value is provided for the DBRMLIB directive, the default value is DBRMLIB. SQL(DBRMLIB) is the equivalent of SQL(DBRMLIB=DBRMLIB).

    On the deployment machine, you must put the DBRM files into a subdirectory of the default directory: %LOCALAPPDATA%\Micro Focus\Enterprise Developer\hcoss\DBRMDataSets. The subdirectory name must match the DBRMLIB name.

    For example, assuming the following:

    Development machine Windows user ID | devuser
    Deployment machine Windows user ID | exeuser
    DBRMLIB directive | SQL(DBRMLIB=REX.PROJECT.DEMO)
    Value of Local HCOSS Directory HCOSS option on both machines | Default setting, %LOCALAPPDATA%\Micro Focus\Enterprise Developer\hcoss\DBRMDataSets

    You then copy the generated DBRM files using the following directory specifications:

    Development Machine | Deployment Machine
    c:\Users\devuser\AppData\Local\Micro Focus\Enterprise Developer\hcoss\DBRMDataSets\REX.PROJECT.DEMO | c:\Users\exeuser\AppData\Local\Micro Focus\Enterprise Developer\hcoss\DBRMDataSets\REX.PROJECT.DEMO
  4. Start HCO for SQL Server from Start > All Programs > Micro Focus Enterprise Server > Data Tools > HCO for SQL Server.
  5. Using the Manage Connections tool, create a connection to the deployment SQL Server machine. For more information, see the Manage Connections Tool topic.
    Important: Be sure that the login credentials you use grant you the permissions necessary to successfully perform the tasks outlined in both the Schema Update Execution and Bind Script Execution sections of the DSN Bind Utility topic.
  6. Using the Manage Packages and Plans tool, bind the DBRM to your deployment SQL Server machine by creating and executing a BIND PACKAGE script command. For complete details, see the Manage Packages and Plans topic.
  7. Test your HCOSS application on the deployment SQL Server machine.
    Note: When running from the command line, if your Enterprise Server installation directory contains spaces, do not enclose the directory specification in quotes when you add it to the PATH environment variable.

Deploy an Application with Customized SQL Error Codes

Copy the mfhcocds.txt file on your development machine, located in the %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer directory by default, to the same directory on your deployment machine.

Deploy an Application with Customized SQL Name Mappings

Copy the DialectMappings.hcomap file on your development machine, located in the %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss directory by default, to the same directory on your deployment machine.

Parent topic: HCO for SQL Server (HCOSS)
Related concepts
DB2 Database Migration Process
Manage Packages and Plans Tool
Deploying Native COBOL Applications
Additional Software Requirements
Extract Schema Tool
Related reference
DSN command


Managing Log Files

Each of the following HCOSS tools generate one or more log files as you use the tool, storing them in folders as specified in your HCOSS options:
  • Manage Connections
  • Extract Schema
  • Define Lists
  • Generate DDL
  • Transfer Data
  • Compare Data
  • Manage Packages and Plans

Within the IDE, we provide a Log File tab for each of these tools where you can view the contents of the log files generated, and delete the log files of your choice. You can also configure your HCOSS options to automatically delete log files older than a given number of days.

Parent topic: HCO for SQL Server (HCOSS)


How to

  • To start HCO for SQL Server
  • To set HCOSS options
  • Manage Connections Tasks
  • To generate a stored procedure definition (SPD) file
  • Migrate Databases Tasks
  • Manage Packages and Plans Tasks
  • Bind Applications
Parent topic: HCO for SQL Server (HCOSS)


To start HCO for SQL Server

  • Click Start > All Programs > Micro Focus Enterprise Server > Data Tools > HCO for SQL Server.
    Note: On Windows 8, Windows 10, and Windows Server 2012, you use the Start screen to invoke programs.
Note:
  • If HCOSS finds a more recent version of SQL Native Client or a more recent version of the ODBC Driver for SQL Server available on your machine, it prompts you with the option to upgrade your existing system and user connections to use the updated driver. You can turn this functionality off by unchecking Enable Checking for New ODBC Drivers on the Connection List tab or by checking Stop asking me on the prompt dialog box.
  • If you are using Windows UAC, you might be prompted to run HCOSS as an administrator when you start HCOSS. See Using HCOSS with Windows User Account Control (UAC) for more information.
Parent topic: How to
Related concepts
HCOSS Toolset
Using HCOSS with Windows User Account Control (UAC)
Related reference
Options


To set HCOSS options

  1. Click Start > All Programs > Micro Focus Enterprise Server > Data Tools > HCO for SQL Server.
    Note: On Windows 8, Windows 10, and Windows Server 2012, you use the Start screen to invoke programs.
  2. From the HCO for SQL Server interface, click Options.
  3. Set options as needed.
    Tip: Context help for each setting appears at the bottom of the window.
  4. Click OK to save your settings.
Parent topic: How to
Related concepts
HCOSS Toolset
Using HCOSS with Windows User Account Control (UAC)
Related reference
Options


Manage Connections Tasks

  • To create a DB2 connection
  • To create a system or user SQL Server connection
  • To edit an existing connection
  • To import a connection
  • To export a connection
  • To repair a connection
Parent topic: How to


To create a DB2 connection

  1. From the HCO for SQL Server interface, click Manage Connections.
  2. On the Connections List tab, select a Connection Type (System or User) for this DB2 connection.
  3. Click New DB2 Connection.
  4. Complete all fields on the form.
  5. If you want HCOSS to remember your ADO.NET password, check Allow Saving ADO.NET Connection Password. Otherwise, the system prompts you for a password each time you connect from other HCOSS tools.
  6. Click Test.
  7. When the connection tests successfully, click OK to clear the message; then click Save.

    The new connection appears on the Connections List located on the Connections List tab.

Parent topic: Manage Connections Tasks


To create a system or user SQL Server connection

  1. Be sure you have added your SQL Server database to Microsoft SQL Server Management Studio.
  2. From the HCO for SQL Server interface, click Manage Connections.
  3. On the Connection List tab, select a Connection Type - System or User - for this SQL Server connection.
  4. From the Connection List tab, click New SQL Server Connection.
  5. Specify appropriate Connection Properties.
    Note: If you have selected Use SQL Server Login and want HCOSS to remember your ADO.NET password, check Allow Saving ADO.NET Connection Password. Otherwise, the system prompts you for a password each time you connect from other HCOSS tools.
  6. Specify appropriate Data Link Properties as follows:
    1. Specify a SQL Server Instance by selecting from the drop-down list, or by typing the name of your SQL Server instance into the field. If you type in the name of your SQL Server instance rather than selecting it from the drop-down list, you must also click Confirm Server.
    2. If you want to use a database other than the default database, check Use a database other than the default database: dbname, and then select an alternative database from the Database drop-down list.
  7. Click Test.
  8. When the connection tests successfully, click OK to clear the message.
  9. Click Save.

    The new connection appears on the Connections List located on the Connections List tab.

Parent topic: Manage Connections Tasks


To edit an existing connection

  1. From the HCO for SQL Server interface, click Manage Connections.
  2. On the Connection List tab, select a connection from the connection list; then click Edit.
  3. Modify the Connection Properties and Data Link Properties as appropriate.
  4. Click Test.
  5. When the connection tests successfully, click OK to clear the message.
  6. Click Save.
Note: When editing a SQL Server connection of the System or User connection type, if HCOSS finds a more recent version of SQL Native Client available on your machine, it prompts you with the option to upgrade the connection to use the updated driver. You can turn this functionality off by unchecking Enable Checking for New ODBC Drivers on the Connection List tab or by checking Stop asking me on the prompt dialog box.
Parent topic: Manage Connections Tasks


To import a connection

  1. From the HCO for SQL Server interface, click Manage Connections.
  2. On the Import tab, type the full path to and filename of an XML (.xml) file containing the exported connection(s) that you want to import, or click the browse button to select a file.
  3. Click Read Available Connections to populate the list.
  4. Select one or more connections to import. Use Ctrl+Click to select multiple connections.
  5. Click Import.
    Note:
    • If one or more of the selected connections uses a provider other than the SQL Native Client, or if you do not have the appropriate database provider installed, the Import button is disabled and you cannot import the connection.
    • When importing an OleDb Data Provider connection, whenever possible, HCOSS uses the same driver version that was in use when the connection was exported. For example, if the exported connection used SQL Server Native Client 10.0, and that version is installed and available for the import, HCOSS uses it. If the version specified is not installed or is not available, HCOSS uses the latest version available for that driver.
    • HCOSS cannot import a connection that has the same name as an existing connection. In this case, HCOSS notifies you that the connection already exists, and does not perform the import of that connection.
  6. When the import is complete, click OK to clear the message. You should see the imported connections on the Connection List found on the Connection List tab.
Parent topic: Manage Connections Tasks


To export a connection

  1. From the HCO for SQL Server interface, click Manage Connections.
  2. From the connection list on the Export tab, select one or more connections you want to export.
  3. In the Export to File field, type the full path to and filename of a file to which you want to export the connection(s), or click the browse button to select or specify a file.
    Note:
    • The default file extension for exported connections is .xml.
    • If you don't specify a path, HCO for SQL Server puts the file into the bin directory of your installation.
    • If you specify an existing file, HCO for SQL Server prompts you to confirm the overwriting of that file.
  4. Click Export.
Parent topic: Manage Connections Tasks


To repair a connection

  1. From the HCO for SQL Server interface, click Manage Connections.
  2. From the Connection List tab, select a Connection Type (System or User) to populate the Connection List grid with connections defined for that type.
  3. From the Connection List grid, select a connection that shows a status of Needs Repair.
  4. Click Repair.
Note: When repairing SQL Server connection of the System or User connection type, HCOSS attempts to use the ODBC driver specified when the connection was created, such as SQL Server Native Client 10.0. If the specified driver version is not available, HCOSS uses the latest available version.
Parent topic: Manage Connections Tasks


To generate a stored procedure definition (SPD) file

  1. Using the Extract Schema tool, extract a schema that contains a stored procedure.
  2. From the HCO for SQL Server interface, click Generate SPD File.
  3. Select either Local or Shared to populate the Schema Extract File drop-down list.
  4. Select a schema extract file from the drop-down list.

    The stored procedures available in the schema extract file show on the Select procedures to generate grid.

  5. Check the box next to each stored procedure you want to generate.
  6. If the fields in the Post Deployment group are enabled, specify the full path to and file name of a post-deployment script in the corresponding File Name field, type the default namespace for the project into the Namespace field, and ensure that Generate changes is checked. See Post-Deployment Script Requirements for complete information.
    Important: When you create your project using the SQL Server Database Project template, you must manually create and add the post-deployment script file to the .Publish project before completing these fields. See To add a post-deployment script for more information.
  7. In the SPD group, type a name for the generated SPD file into the File Name field. Do not include the .spd file extension.
  8. If your generated SPD file passes parameters to a SQL CLR Stored Procedure definition routine, and you want to pass all of those parameters as fixed length, check Generate fixed-length parameters.
  9. If you want to also generate a COBOL wrapper program and automatically add it and the generated SPD file to your current project, check Add file to active project. Optional.
    Note: The Add file to active project check box is available only when you open HCOSS from within the IDE and you have an active SQL CLR Database project open in . If you do not add the SPD file and COBOL wrapper program to the project at this time, you can add them to any project as Existing Items.
  10. Click Generate.
  11. Specify a file location if prompted.
Parent topic: How to
Related concepts
Generate SPD File tool
Related tasks
To extract DB2 schemas
Related reference
Generate SPD File tab


Migrate Databases Tasks

  • To extract DB2 schemas
  • To modify a schema extract file
  • To export and import DB2 schemas
  • To assess data migration
  • To export data assessment results
  • To define an object transfer list
  • To generate and execute DDL
  • To customize generated DDL
  • To customize schema mappings in DDL
  • To transfer data
  • To customize a transfer data task
  • To compare transferred data
  • To run customized data comparisons
Parent topic: How to


To extract DB2 schemas

  1. From the HCOSS Extract Schema tool, click the Schema Extract tab.
  2. From the DB2 Connection drop-down list, select the DB2 connection you created using the Manage Connections tool that points to the DB2 database containing the schema objects that you want to extract.
  3. If prompted, provide your user ID and password.
  4. Click New.
  5. In the Schema Extract Name field, type a name for the generated schema extract file.
  6. In the Metadata/Catalog Schema Name field, type the name of a schema containing alternative views of the SYSIBM table. Optional.
    Note: This feature enables users to access the information in SYSIBM tables without having access to the SYSIBM catalog. In this case, you must create the alternative schema before running the Extract Schema tool.
  7. Click OK.
  8. On the Schema Extract tab, choose one of the following:
    Local | To save the generated schema extract file to the directory specified by the Local HCOSS Directory HCOSS option.
    Shared | To save the generated schema extract file to the directory specified by the Shared HCOSS Directory HCOSS option.
  9. On the Select schema(s) to extract list, check the box that corresponds to each schema you want to extract.
  10. In the Table Row Count group, select one of the following:
    • Estimated using schema statistics - to record the estimated table row count based on the schema statistics stored in SYSIBM.SYSTABLES. Use this option to improve performance.
    • Both Estimated using schema statistics and Actual using SELECT BIG_COUNT(*) - to record both the estimated table row count and the actual row count as retrieved using a SELECT BIG-COUNT(*) query. Use this option to provide accuracy.
  11. Click Extract.
  12. On the Results tab, verify that the schema extract file has been generated properly.
    Note: If you get a -551 SQL error extracting a table, no schema is extracted. To correct this, have your DB2 DBA grant you READ access to the table that generated the error; then rerun the Extract Schema tool.
  13. On the Schema Extract tab, click Save to save the settings.
Parent topic: Migrate Databases Tasks
Related concepts
Extract Schema Tool
Related tasks
To generate a stored procedure definition (SPD) file
To export and import DB2 schemas
Related reference
MFExtractSchemaInfo command
Extract Schema Tool Log Files
Extract Schema Tool Error Messages
Required DB2 Catalog Tables
Schema Extract tab
Create New Schema Extract
Results tab


To modify a schema extract file

  1. From the HCOSS Extract Schema tool, click the Schema Extract tab.
  2. Select an existing schema extract file from the Schema Extract Name drop-down list.
  3. Using the fields and controls on the Schema Extract tab change the settings as required.
    Note: If you change the properties from Local to Shared, or vice versa, you have the following options:
    • Move the existing extract file to the new location
    • Copy the existing extract file to the new location
    • Neither move nor copy the existing extract file
  4. Click Extract.
  5. On the Results tab, verify that the schema extract file has been generated properly.
    Note: If you get a -551 SQL error extracting a table, no schema is extracted. To correct this, have your DB2 DBA grant you READ access to the table that generated the error; then rerun the Extract Schema tool.
  6. On the Schema Extract tab, click Save to save the new settings.
Parent topic: Migrate Databases Tasks
Related concepts
Extract Schema Tool
Related reference
MFExtractSchemaInfo command
Extract Schema Tool Log Files
Extract Schema Tool Error Messages
Required DB2 Catalog Tables
Schema Extract tab
Results tab


To export and import DB2 schemas

To export a schema:

  1. From the Schema Extract tab, create a schema extract file or open an existing schema extract file from the Schema Extract Name drop-down list.
  2. Click Export.
  3. Select a location and provide a file name for the exported schema file. Do not include a file extension.
  4. Ensure that the Save as type field is set to Micro Focus HCOSS Schema Extract Files(*.hcodbs); then click Save.
  5. If a schema extract file with the same name exists in the same location, you are prompted to confirm that you want to overwrite it.

To import a schema:

  1. From the Schema Extract tab, click Import.
  2. Browse to and select an exported schema file. These files have a .hcodbs file extension.
  3. Click Open.
Parent topic: Migrate Databases Tasks
Related tasks
To extract DB2 schemas


To assess data migration

  1. From the HCOSS Assess Data Migration tool, click the Data Assessment Tasks tab.
  2. From the DB2 Connection drop-down list, select the DB2 connection that contains the extracted schema you want to assess.
  3. Do one of the following:
    • To define a new Data Assessment task:
      1. Click New.
      2. In the Name field, type a name for the data assessment task.
      3. From the Schema Extract drop-down list, select an existing schema extract file.
      4. Click OK.
    • To edit an existing data assessment task, select either the Local or Shared radio button; then select a task from the Available Assessments drop-down list.
  4. Choose one of the following to apply to the Available Assessments drop-down list:
    Local | To save the generated data assessment task to the directory specified by the Local HCOSS Directory HCOSS option.
    Shared | To save the generated data assessment task to the directory specified by the Shared HCOSS Directory HCOSS option.
  5. Choose one of the following to apply to the Associated Schema Extract drop-down list:
    Local | To show local extracted schemas on the Associated Schema Extract drop-down list.
    Shared | To show shared extracted schemas on the Associated Schema Extract drop-down list.
  6. From the Associated Schema Extract drop-down list, select an extracted schema created using the Extract Schema tool.

    This populates the Table List with information in the selected schema extract.

  7. Click Save to save the data assessment task so that it is available for future editing.

    At this point, you can browse the information in the schema extract file, and you can optionally make changes. If you want to make changes to the file, continue with step 8.

  8. From the DB2 Connection drop-down list, select the DB2 database connection you want to use when updating the schema extract file.
  9. To change the information in the extracted schema, optionally choose one of the following actions for each table on the grid:
    • Change the Count-Type. The default type listed for each column depends on which Table Row Count option you chose when you extracted the schema.
    • Change the Transfer Option from HCOSS to OTHER for tables containing data that you do not want to migrate.
  10. To update the schema extract file with changes on the Table List grid, click Update Row Count. Any error messages are shown in the Update Results window on the Results tab.
  11. Click Save Options to save the changes you've made in the Table List grid.
Parent topic: Migrate Databases Tasks


To export data assessment results

To export data assessment results as a CSV file:

  1. Perform the analysis.
  2. Click Export Details (csv).
  3. In the File Name field supply a filename and specify a location. If you specify a file name that doesn't exist, it is created. If you specify a file name that already exists, you will be prompted to confirm that you want to overwrite the existing file.

To export data assessment results as a text file:

  1. Perform the analysis.
  2. Click Export Report (txt).
  3. In the File Name field supply a filename and specify a location. If you specify a file name that doesn't exist, it is created. If you specify a file name that already exists, you will be prompted to confirm that you want to overwrite the existing file.
Parent topic: Migrate Databases Tasks


To define an object transfer list

  1. From the HCOSS Define Lists tool, click the Transfer Lists tab.
  2. Do one of the following:
    • To define a new transfer list:
      1. Click New.
      2. In the Name field, type a name for the transfer list file.
      3. Click OK.
    • To edit an existing transfer list, select an existing list from the Available Transfer Lists drop-down list.
  3. Choose one of the following to apply to the Available Transfer Lists drop-down list:
    Local | To save the generated transfer list file to the directory specified by the Local HCOSS Directory HCOSS option.
    Shared | To save the generated transfer list file to the directory specified by the Shared HCOSS Directory HCOSS option.
  4. Choose one of the following to apply to the Associated Schema Extract drop-down list:
    Local | To show local extracted schemas on the Associated Schema Extact drop-down list.
    Shared | To show shared extracted schemas on the Associated Schema Extact drop-down list.
  5. From the Associated Schema Extract drop-down list, select a schema extract file created using the Extract Schema tool.

    The objects available from the Schema Extract file appear on the Available Objects list.

  6. To filter the list of available objects, use the fields in the Object Filtering and Selection group. Optional.
  7. Do one or more of the following to select objects to transfer:
    • To transfer one or more objects on the Available Objects list, select each object you want to transfer using a combination of mouse clicks and the Ctrl or Shift keys; then click Add.
    • To transfer all of the objects on the Available Objects list, click Add All.
    Note: Objects dependent on selected objects are added automatically.
  8. To remove objects from the Selected Objects list, do one of the following:
    • To remove one or more of the objects on the Selected Objects list, select each object you want to remove using a combination of mouse clicks and the Ctrl or Shift keys; then click Remove.
    • To remove all of the objects on the Selected Objects list, click Remove All.
    Optional.
  9. Click Save.
Parent topic: Migrate Databases Tasks
Related concepts
Define Lists Tool
Related reference
MFObjectList command
Define Lists Tool Log Files
Define Lists Tool Error Messages
Transfer Lists tab
Create New List dialog box


To generate and execute DDL

  1. From the HCOSS Generate DDL tool, click the DDL Tasks tab.
  2. Do one of the following:
    • To define a new DDL task:
      1. Click New.
      2. In the Name field, type a name for the DDL task file.
      3. Click OK.
    • To edit an existing DDL task, select an existing task from the Available Tasks drop-down list.
  3. Choose one of the following to apply to the Available Tasks drop-down list:
    Local | To save the generated DDL task file to the directory specified by the Local HCOSS Directory HCOSS option.
    Shared | To save the generated DDL task file to the directory specified by the Shared HCOSS Directory HCOSS option.
  4. Choose one of the following to apply to the Associated Transfer List drop-down list:
    Local | To show local transfer lists on the Associated Transfer List drop-down list.
    Shared | To show shared transfer lists on the Associated Transfer List drop-down list.
  5. From the Associated Transfer Lists drop-down list, select a transfer list file created using the Define Lists tool.
  6. To define the DDL behavior, select either Drop and create objects or Restore missing objects.
  7. From the Connection for Execute drop-down list, select a SQL Server connection previously defined using the Manage Connections tool.
  8. Optionally, do one or more of the following:
    • To customize your generated DDL, click Customize. See To customize generated DDL for more information.
    • To change the default schema mappings, click Schema Mappings. See To customize schema mappings in DLL for more information.
    • To populate coded character set identifiers (CCSIDs), thus preserving the mainframe text sort order, check Preserve mainframe text sort order. If left unchecked, the sort order is the default SQL Server order specified for the database.
    • To check the DDL task specifications against a test SQL Server data source, specify a SQL Server data source in the Connection for Check drop-down list; then click Check. Results are displayed on the Results tab.
    • To save the SQL generated for the DDL as an SQL script, click Export SQL Script.
  9. Click Save to save the DDL task.
  10. Click Execute.
  11. Click the Results tab to review the execution results.
Parent topic: Migrate Databases Tasks
Related concepts
Generate DDL Tool
Related tasks
To customize generated DDL
To customize schema mappings in DDL
Related reference
MFDDLConverter command
Generate DDL Tool Log Files
Generate DDL Tool Error Messages
DDL Tasks tab
Create New DDL Task dialog box
Customize DDL tab
Schema Mappings tab
Results tab


To customize generated DDL

  1. From the HCOSS Generate DDL tool, either create a new DDL task or open an available DDL task.
  2. Click the Customize DDL tab.
  3. On the Objects grid, click a schema object you want to customize.
  4. In the Customized DDL window, edit the DDL code to reflect the changes you desire.
  5. Click Save All to save your changes.
    Note: The code shown in the Generated DDL window is the DDL code that HCOSS generates by default. However, once you make and save changes to the code in the Customized DDL window, HCOSS generates your customized code instead of the default code.
  6. Repeat steps 3 through 5 for each schema object you want to customize.
Parent topic: Migrate Databases Tasks
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
Related reference
MFDDLConverter command
Generate DDL Tool Log Files
Generate DDL Tool Error Messages
DDL Tasks tab
Create New DDL Task dialog box
Customize DDL tab
Schema Mappings tab
Results tab


To customize schema mappings in DDL

  1. From the HCOSS Generate DDL tool, either create a new DDL task or open an available DDL task.
  2. Click the Schema Mappings tab.
  3. In the SQL Server Schema Name column, double-click the entry you want to change.
  4. Edit the mapping to reflect the appropriate SQL Server schema name.
    Note: The changes you make are automatically saved when you click outside of the SQL Server Schema Name column.
Parent topic: Migrate Databases Tasks
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
Related reference
MFDDLConverter command
Generate DDL Tool Log Files
Generate DDL Tool Error Messages
DDL Tasks tab
Create New DDL Task dialog box
Customize DDL tab
Schema Mappings tab
Results tab


To transfer data

  1. From the HCOSS Transfer Data tool, click the Transfer Data Tasks tab.
  2. Do one of the following:
    • To define a new transfer data task:
      1. Click New.
      2. In the Name field, type a name for the transfer data task file.
      3. Click OK.
    • To edit an existing transfer data task, select an existing task from the Available Tasks drop-down list.
  3. Choose one of the following to apply to the Available Tasks drop-down list:
    Local | To save the transfer data task file to the directory specified by the Local HCOSS Directory HCOSS option.
    Shared | To save the transfer data task file to the directory specified by the Shared HCOSS Directory HCOSS option.
  4. Choose one of the following to apply to the Associated DDL Task drop-down list:
    Local | To show local DDL tasks on the Associated DDL Task drop-down list.
    Shared | To show shared DDL tasks on the Associated DDL Task drop-down list.
  5. From the Associated DDL Task drop-down list, select a DDL task file created using the Generate DDL tool.
  6. From the Source Connection drop-down list, select a DB2 connection previously defined using the Manage Connections tool.
  7. From the Destination Connection drop-down list, select a SQL Server connection previously defined using the Manage Connections tool.
  8. To customize your transfer data task, click Customize. See To customize a transfer data task for more information. Optional.
  9. Click Save to save the transfer data task.
  10. To export the transfer data task as one or more SSIS packages, click Export as SSIS Packages. Optional.
  11. Click Transfer.
  12. On the Results tab, verify that the data transfer has completed properly.
Parent topic: Migrate Databases Tasks
Related concepts
Transfer Data Tool
Related tasks
To customize a transfer data task
Related reference
MFDataTransferCtlr command
Transfer Data Tool Log Files
Transfer Data Tool Error Messages
Transfer Data Tasks tab
Create New Transfer Data Task dialog box
Customize Transfer Data tab
Results tab


To customize a transfer data task

  1. From the HCOSS Transfer Data tool, either create a new transfer data task or open an available transfer data task.
  2. Click the Customize Transfer Data tab.
  3. Do one or more of the following to customize the task. All are optional:
    • Edit the Seq, Schema name, Name, or Buffer rows column for any entry on the Tables grid.
      Note:
      • Be careful that any new values you enter into column fields are valid within the context of the transfer task. Invalid values can cause Build Query failures.
      • Edits made directly to the Query column are not saved.
    • Change or set the controls in the Transfer Task Options group to affect all schemas and tables.
    • Build a WHERE or an ORDER BY into a SELECT statement:
      1. On the Tables grid, double-click the first column on the left-hand side of the grid for the object you want to customize.
      2. Use the fields and controls in the WHERE/ORDER BY in SELECT group to construct the clause.
      3. Click Update to add the WHERE or ORDER BY to the query statement.
    • Select a method for handling source row data from the Source Row Data Count group.
      Note:
      • The default setting for Source Row Data Count when you have not specified a WHERE clause is Estimate using schema statistics. If you have specified a WHERE clause, the default is Acutal using COUNT_BIG(*).
      • You can override the default by specifically selecting an option from the group with one exception. If the default setting is Acutal using COUNT_BIG(*), you cannot override it by setting it to Estimate using schema statistics.
  4. Click Save All to save all customizations.
  5. Optionally, click Transfer to immediately transfer the data.
    Note: You can also transfer the data from the Transfer Data Tasks tab.
Parent topic: Migrate Databases Tasks
Related concepts
Transfer Data Tool
Related tasks
To transfer data
Related reference
MFDataTransferCtlr command
Transfer Data Tool Log Files
Transfer Data Tool Error Messages
Transfer Data Tasks tab
Create New Transfer Data Task dialog box
Customize Transfer Data tab
Results tab


To compare transferred data

  1. From the HCOSS Compare Data tool, click the Compare Data Tasks tab.
  2. Do one of the following:
    • To define a new compare data task:
      1. Click New.
      2. In the Name field, type a name for the compare data task file.
      3. Click OK.
    • To edit an existing compare data task, select an existing task from the Available Tasks drop-down list.
  3. Choose one of the following to apply to the Available Tasks drop-down list:
    Local | To save the compare data task file to the directory specified by the Local HCOSS Directory HCOSS option.
    Shared | To save the compare data task file to the directory specified by the Shared HCOSS Directory HCOSS option.
  4. Choose one of the following to apply to the Associated DDL Task drop-down list:
    Local | To show local DDL tasks on the Associated DDL Task drop-down list.
    Shared | To show shared DDL tasks on the Associated DDL Task drop-down list.
  5. From the Associated DDL Task drop-down list, select a DDL task file created using the Generate DDL tool.
  6. From the Source Connection drop-down list, select a DB2 connection previously defined using the Manage Connections tool.
  7. From the Destination Connection drop-down list, select a SQL Server connection previously defined using the Manage Connections tool.
  8. To customize your compare data task, click Customize. See To run customized data comparisons for more information. Optional.
  9. Click Save to save the compare data task.
  10. Click Compare.
  11. On the Results tab, verify that the results of the comparison.
Parent topic: Migrate Databases Tasks
Related concepts
Compare Data Tool
Related tasks
To run customized data comparisons
Related reference
MFTestConversion command
Compare Data Tool Log Files
Compare Data Tool Error Messages
Compare Data Tasks tab
Create New Compare Data Task dialog box
Customize Compare Data tab
Results tab


To run customized data comparisons

  1. From the HCOSS Compare Data tool, either create a new compare data task or open an available compare data task.
  2. Click the Customize Compare Data tab.
  3. On the Source Schemas and Tables tree view, expand the tree and check a table you want to customize. This populates the Customized Query Pair window with the query associated with the checked table.
  4. Do one or more of the following:
    • Edit the query code in the Customized Query Pair window; then click Compare. Results are shown on the Results tab.
    • Build a WHERE or an ORDER BY clause into the SELECT statement:
      1. Use the fields and controls in the WHERE/ORDER BY in SELECT group to construct the clause. When you click > or <, HCOSS updates the code in the Customized Query Pair window.
      2. Click Compare. Results are shown on the Results tab.
      3. On the Customize Compare Data tab, click Save All to save the changes.
    Note: HCOSS does not save manual changes made to code in the Customized Query Pair window.
Parent topic: Migrate Databases Tasks
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
Related reference
MFTestConversion command
Compare Data Tool Log Files
Compare Data Tool Error Messages
Compare Data Tasks tab
Create New Compare Data Task dialog box
Customize Compare Data tab
Results tab


Manage Packages and Plans Tasks

  • To create a bind script file
  • To open an existing bind script file
  • To create a new package
  • To create a new plan
  • To edit an existing BIND command
  • To execute one or all bind script lines
  • To free one or more packages
  • To free one plan or all plans
Parent topic: How to


To create a bind script file

  1. From the HCOSS Manage Packages and Plans tool, click the Bind Scripts tab.
  2. If you have a script file open, click New to clear the page.
  3. Specify a SQL Server Connection.
  4. Add one or more bind script entries by creating one or more Packages or Plans.
  5. Click Save As to name and save the file to a location of your choosing. All bind script files are in XML format and have the file extension .hcodsn.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Related reference
Bind Scripts tab


To open an existing bind script file

  1. From the HCOSS Manage Packages and Plans tool, click the Bind Scripts tab.
  2. Click Open to locate and select an existing bind script file. Bind script files have the file extension .hcodsn.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Related reference
Bind Scripts tab


To create a new package

  1. From the HCOSS Manage Packages and Plans tool, either create or open a bind script file.
  2. Click New Package.
  3. In the Collection Name field, type a name for the collection in which to store the package.
  4. Select an action. If you select Replace Version, type the version you want to replace into the corresponding field.
  5. From the Library Name drop-down list, select the library that contains the source member from which you want to create the package. The default is DBRMLIB.
  6. From the Member Name drop-down list, select the member you want to action.
  7. If you have a qualifier you would like to specify, type it into the Default Qualifier field.
  8. Click Execute. This generates a script command and places it onto the list of Bind Script Entries on the Bind Scripts tab.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Package Specifications
Related reference
Bind Packages tab


To create a new plan

  1. From the HCOSS Manage Packages and Plans tool, either create or open a bind script file.
  2. Click New Plan.
  3. In the Plan Name field, type a name for the plan.
  4. Select an action.
  5. Do one of the following:
    • To bind packages into the plan, select Packages mode. In this case, all versions of each package are available to the plan.
    • To bind DBRM members directly to the plan, select DBRM Members mode. In this case, HCOSS expects to find these members in the default DBRM library.
    • To bind one or more DBRM libraries to the plan, including all of the members in those libraries, select DBRM Libraries mode. In this case, HCOSS searches the libraries for DBRM members in the order in which the libraries appear on the Selected Libraries list. HCOSS uses the first instance of a specified member that it finds.
  6. If you have a qualifier you would like to specify, type it into the Default Qualifier field.
    Note: HCOSS applies plan qualifiers to DBRM members specified in the plan; however, packages included in the plan use the qualifier specified for the package when it was executed, ignoring any specified plan qualifier.
  7. Depending on the mode you have selected, use the other lists and fields on this page to add packages or DBRM members to the plan, or to remove them from the plan. You can use the Search field above each list to narrow the scope of the list. Use the % character as a wild card.
  8. Click either Add to Script to add the generated script command to the list of Bind Script Entries on the Bind Scripts tab, or click Execute to add the generated script and also execute the script commands thereby updating the SQL Server database.
    Note: If you do not execute the command at this time, you can execute it from the Bind Scripts tab to update the SQL Server database. You must eventually execute the command for the bind to take place.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Plan Specifications
Related reference
Bind Plans tab


To edit an existing BIND command

  1. From the HCOSS Manage Packages and Plans tool, open a bind script file.
  2. Select a command on the Bind Script Entries list.
  3. Click Edit.
  4. Make any desired changes to the specification. For BIND PLAN commands, the available lists and fields on this page vary depending on the selected mode. You can use the Search field above each list to narrow the scope of the list. Use the % character as a wild card.
    Note: For BIND PLAN commands that include DBRM members, you can add one or more libraries in which to search for the specified DBRM members by selecting DBRM Libraries mode. In this case, you can click Move Up or Move Down to change the search order.
  5. Do one of the following:
    • Click Execute to generate and execute the BIND command and add it to your bind script.
    • Click Update in Script to generate the BIND command and add it to your script for execution at a later time.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Package Specifications
Plan Specifications
Related reference
Bind Packages tab
Bind Plans tab
Bind Scripts tab


To execute one or all bind script lines

  1. From the HCOSS Manage Packages and Plans tool, either create or open a bind script file.
  2. Ensure that the script lines on the Bind Script Entries list appear in the order in which you want to execute them. If not, select a line and click Move Up or Move Down to change its position.
  3. Do one of the following:
    • To execute one script line only, select the script line you want to execute; then click Execute Selected. In this case, if a script command fails, HCOSS displays an error message.
    • To execute all script lines in the order in which they appear on the list, click Execute All. In this case, if a script command fails, HCOSS displays an error message enabling you to click Cancel to cancel all further execution, or OK to continue with the next script command.
    Note:
    • You must successfully execute all BIND PLAN script lines to make the plans available to your run-time application.
    • All bind script execution results appear on the Results tab.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Related reference
Bind Scripts tab
Results tab


To free one or more packages

  1. From the HCOSS interface, use the Manage Connections tool to ensure you have an active connection to your SQL Server database.
  2. Click Manage Packages and Plans to start the tool.
  3. From the Bind Scripts tab, select a SQL Server Connection from the drop-down list.
  4. Click the Free Packages tab.
  5. Do one of the following:
    • To free all bound packages listed on the Bound Packages list, click Free All Packages.
    • To free one or more packages:
      1. To show version information for each package on the Bound Packages list, check Show package version information. This turns on the Version column within the grid (Optional).
      2. On the Bound Packages list, select one or more packages to remove from your SQL Server database.
        Note: To select or unselect all packages, right-click and choose the appropriate menu option.
      3. Click Free Package(s).
  6. Click OK to confirm.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Freeing Packages and Plans
Related reference
Free Packages tab


To free one plan or all plans

  1. From the HCOSS interface, use the Manage Connections tool to ensure you have an active connection to your SQL Server database.
  2. Click Manage Packages and Plans to start the tool.
  3. From the Bind Scripts tab, select a SQL Server Connection from the drop-down list.
  4. Click the Free Plans tab.
  5. Do one of the following:
    • To free all bound plans listed on the Bound Plans list, click Free All Plans.
    • To free a single plan:
      1. On the Bound Plans list, select a plan you want to remove from your SQL Server database.
      2. View the details of the plan by doing one or more of the following (optional):
        • Select either the Members or Packages mode to view the contents of the plan.
        • When in Packages mode, check Expand PKLIST to show package details if you want to view every package that resulted from the binding.
        • When Expand PKLIST to show package details is checked, you can also check Show package version information to display version information for each package.
      3. Click Free Plan.
  6. Click OK to confirm.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Freeing Packages and Plans
Related reference
Free Plans tab


Bind Applications

  • To bind from the command line
  • To manually code a bind script file
  • To bind from JCL
Parent topic: How to


To bind from the command line

  1. Create a bind script file using the Manage Packages and Plans tool, or manually in a text editor. If you create the file in a text editor, be sure to give it a file extension of .hcodsn.
    Note: For a listing of commands that are valid in HCOSS bind script files, see the topic Bind Script Commands.
  2. Using the Manage Connections tool, connect to your SQL Server database with a login ID and password that grants you permission to update the SYSIBM table.
  3. Open an Enterprise Server command prompt.
  4. Enter the following command:

    DSN SYSTEM(SQLServerConnection) @"bindScriptFile"

    where SQLServerConnection is the name of your SQL Server connection, and bindScriptFile is the full path to and filename of your bind script file.

Parent topic: Bind Applications
Related concepts
DSN Bind Utility
Binding Applications
Related tasks
To manually code a bind script file
Related reference
DSN command
Bind Script Commands


To manually code a bind script file

  1. Open a text editor of your choice.
  2. Type each command on its own line.
    Note: For a listing of commands that are valid in HCOSS bind script files, see the topic Bind Script Commands.
  3. At the end of the file, type END.
  4. Save the file to a location of your choice, using a .hcodsn filename extension.
Parent topic: Bind Applications
Related concepts
DSN Bind Utility
Binding Applications
Related tasks
To bind from the command line
Related reference
DSN command
Bind Script Commands


To bind from JCL

  1. In your JCL, code a DSN statement followed by appropriate BIND statements.
    //SYSTSIN  DD *
  DSN SYSTEM(XAResourceName)
  BIND bindArguments
  [BIND...]
  END

    For example:

    //SYSTSIN  DD *
  DSN SYSTEM(HCODemo)
  BIND PLAN(TWOPACKAGESET) ACTION(REPLACE) LIBRARY(DBRMLIB) -
  MEMBER(TWOPACKAGESET) QUALIFIER(PROD)
  END
  2. Save your JCL.
Note: For a listing of DSN commands supported by HCOSS, see the topic Bind Script Commands.
Parent topic: Bind Applications


Reference

  • Command Line Reference
  • Required DB2 Catalog Tables
  • DB2 to SQL Server Conversion Reference
  • Bind Script Commands
  • Messages
  • Log Files
  • User Interface Reference
Parent topic: HCO for SQL Server (HCOSS)


Command Line Reference

  • MFDataTransferCtlr command
    Executes the HCOSS Transfer Data tool from the command line.
  • MFDDLConverter command
    Executes the HCOSS Generate DDL tool from the command line.
  • MFExtractSchemaInfo command
    Executes the HCOSS Extract Schema tool from the command line.
  • MFObjectList command
    Executes the HCOSS Define Lists tool from the command line.
  • MFTestConversion command
    Executes the HCOSS Compare Data tool from the command line.
  • COMPARE Command File
    Explains how to code a COMPARE command file to use with the MFTestConversion command, IN parameter.
  • DSN command
    Executes the DSN Bind utility, which performs schema updates as necessary and executes the commands contained in an HCOSS bind script file.
Parent topic: Reference


MFDataTransferCtlr command

Executes the HCOSS Transfer Data tool from the command line.

Syntax:

MFDataTransferCtlr DB2=DB2dsn;
                   [U1=DB2userID;]
                   [P1=DB2Password;]
                   SRV=SQLServerDSN;
                   [U2=SQLServerUserID;]
                   [P2=SQLServerPassword;]
                   X=["]DataTransferList["];
                   [XLocal={TRUE | FALSE};]
                   [TRIG={TRUE | FALSE};]
                   [CONSTR={TRUE | FALSE};]
                   [ErrROW={TRUE | FALSE};]
                   [TYPELOG={CONSOLE | FILE | BOTH};]

Parameters:

DB2
The name of a cataloged and registered DB2 data source.
U1
The user ID required to access the DB2 data source specified by the DB2 parameter, if applicable.
P1
The password required for the user ID specified by the U1 parameter, if applicable.
SRV
The name of a cataloged and registered SQL Server data source.
U2
The user ID required to access the SQL Server data source specified by the SRV parameter. Not required when using Windows authentication.
P2
The password required for the user ID specified by the U2 parameter, if applicable.
X
The name of a transfer data task file containing a list of tables to be transferred and the queries required to transfer the data. Do not specify a file extension. The file extension for a transfer data task file is .hcodtt. If the transfer data task file name contains spaces, surround it with a set of double quotes ("). You can create a transfer data task file using the UI version of the HCOSS Transfer Data tool, or you can create one manually in a text editor. If you create a transfer data task file using the UI version of the tool, its location is determined by the selection of either the Local or Shared button for the transfer data task. If you create a data transfer task file manually, you must store it in the \DataTasks subdirectory of either the directory specified by the Local HCOSS Directory HCOSS option or the Shared HCOSS Directory HCOSS option.
XLocal
Determines the location of the transfer data task file. Transfer data task files are stored in the \DataTasks subdirectory of either of the following, depending on the value specified:
TRUE | Directory specified by the Local HCOSS Directory HCOSS option. Default.
FALSE | Directory specified by the Shared HCOSS Directory HCOSS option.
TRIG
Specifies whether or not to fire all triggers during the data transfer. Default is FALSE.
CONSTR
Specifies whether or not SQL Server performs all defined checks during the data transfer. Default is FALSE.
ErrROW
Specifies whether or not HCOSS logs errors encountered during the data transfer. Default is FALSE.
TYPELOG
Sets the type of logging to perform. Defaults to the equivalent of the value specified for the Type of logging to do HCOSS option.

Comments:

Before running this tool, be sure that the appropriate target tables exist in the SQL Server database.

Examples:

MFDataTransferCtlr DB2=MVS91; SRV=HCODemo; X=LocalTransferList
MFDataTransferCtlr DB2=MVS91; SRV=HCODemo; X=SharedTransferList; XLocal=FALSE
Parent topic: Command Line Reference
Related concepts
Transfer Data Tool
Related tasks
To transfer data
To customize a transfer data task
Related reference
Transfer Data Tool Log Files
Transfer Data Tool Error Messages


MFDDLConverter command

Executes the HCOSS Generate DDL tool from the command line.

Syntax

MFDDLConverter S=schemaExtractFile;
               [SLocal={TRUE | FALSE};]
               O=["]DDLOutputFile["];
               DROP={DR | CNE};
               SYSIBM={TRUE | FALSE};
               [M=["]dataMappingFile["];]
               [TYPE={TABLE | VIEW | ALL};]
               [SCHEMA=DB2Schema1[, DB2Schema2 ...];]
               [NAME=objectName;]
               [ROWSIZE={TRUE | FALSE};]
               [INCDEP={TRUE | FALSE};]
               [STITCH={TRUE | FALSE};]
               [TYPELOG={CONSOLE | FILE | BOTH};]
               [FOOTER={TRUE | FALSE};]
               [CCSID={KEEP | IGNORE};]

Parameters:

S
The name of a schema extract file generated using the HCOSS Schema Extract tool. Do not specify a file extension.
SLocal
Specifies the location of the generated schema extract file. Schema extract files are stored in the \Schemas subdirectory of either of the following, depending on the value specified:
TRUE | Directory specified by the Local HCOSS Directory HCOSS option. Default.
FALSE | Directory specified by the Shared HCOSS Directory HCOSS option.
O
The full path to and filename of the generated DDL command file (usually given a .sql file extension). If this specification contains spaces, enclose it in double quotes (").
DROP
Determines how objects are handled in the generated DDL.
DR | Drop and recreate all objects
CNE | Create a new database object for each object in the object list that does not already exist in the database
SYSIBM
Specifies whether or not to include the SYSIBM schema in the generated DDL. Both the SYSIBM schema and its dependent objects are included when set to TRUE; however, the SYSIBM schema and its dependent objects must be present in the schema extract file to be included in the generated DDL.
M
Full path to and filename of the HCOSS data mapping file. If this specification contains spaces, enclose it in double quotes ("). Defaults to %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss\DataMappings.hcomap.
TYPE
Limits objects to tables only or views only. Default is ALL.
SCHEMA
The name of one or more valid DB2 schemas to include in the generated DDL. Separate schema names with a comma (,). You may also use the % wild card character in schema names. Defaults to all schemas in the object list file.
NAME
Filters the generated DDL to include only the specified DB2 table or view name. You may use the % wild card character in table and view names. Defaults to all table and view names.
ROWSIZE
Specifies whether or not to check table column widths to determine if they exceed the SQL Server row width limit of 8060 and write the information to the log file.
TRUE | Check table column widths.
FALSE | Do not check table column widths. Default.
INCDEP
Specifies whether or not to include table and view dependencies when processing objects.
TRUE | Include table and view dependencies.
FALSE | Do not include table and view dependencies. Default.
STITCH
Specifies whether or not to include a DDL header in the generated DDL:
TRUE | Include DDL header.
FALSE | Exclude DDL header. Default.
TYPELOG
Sets the type of logging to perform. Defaults to the equivalent of the value specified for the Type of logging to do HCOSS option.
FOOTER
Specifies whether or not to include a DDL footer in the generated DDL:
TRUE | Include DDL footer. Default.
FALSE | Exclude DDL footer.
CSSID
Specifies whether or not to preserve the mainframe sort order for text columns:
KEEP | Preserves the mainframe sort order by adding a CCSID clause to the table definition.
IGNORE | Returns text columns in the order specified by the SQL Server target database or table collation identifier. Default.

Example:

MFDDLConverter S=MySchemaExtract; O=c:\ProgramData\MyDDL.sql; DROP=DR; SYSIBM=TRUE
Parent topic: Command Line Reference
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL
Related reference
Generate DDL Tool Log Files
Generate DDL Tool Error Messages


MFExtractSchemaInfo command

Executes the HCOSS Extract Schema tool from the command line.

Syntax:

MFExtractSchemaInfo [DB2=DB2Connection;]
                    [ACTION={DELETE | EXTRACT | EXPORT | IMPORT | LIST};]
                    [U=DB2UserID;]
                    [P=DB2Password;]
                    [{NAME | OUT}=SchemaExtractFileName;]
                    [{OUTLocal={TRUE | FALSE}} |
                        LOCATION={LOCAL | SHARED}};]
                    [{SCHEMA={* | DB2Schema1[, DB2Schema2 ...]} |
                       TBS={DB2Tablespace1[, DB2Tablespace2 ...]}}];
                    [PATH=DirectoryPath;]
                    [ROWCOUNT={ESTIMATE | EXACT};]
                    [CATALOG=DB2SchemaName;]
                    [TYPELOG={CONSOLE | FILE | BOTH};]

Parameters:

DB2
The name of a cataloged DB2 connection. Required when ACTION=EXTRACT, which is the default setting.
ACTION
Specifies the action to perform:
DELETE | Deletes the schema extract file.
EXTRACT | Extract the schema(s) specified by the SCHEMA parameter. Default.
EXPORT | Copy the generated schema extract file to the directory specified by the PATH parameter, enabling you to use it to import the schema into the tool when the mainframe is not available.
IMPORT | Import a previously exported schema extract file, located in the directory specified by the PATH parameter.
LIST | Outputs a list to the console, showing the schema extract files located in the directory specified by the OUTLocal parameter setting.
The following matrix shows the additional required and optional parameters for each ACTION value:
ACTION
Parameter | DELETE | EXTRACT | EXPORT | IMPORT | LIST
DB2 | N/A | Required | N/A | N/A | N/A
U | N/A | Optional | N/A | N/A | N/A
P | N/A | Optional | N/A | N/A | N/A
NAME | OUT | Required | Required | Required | Required | N/A
OUTLocal | Optional | Optional | Optional | Optional | Optional
LOCATION | Optional | Optional | Optional | Optional | Optional
SCHEMA | TBS | N/A | Required | N/A | N/A | N/A
PATH | N/A | N/A | Required | Required | N/A
ROWCOUNT | N/A | Optional | N/A | N/A | N/A
CATALOG | N/A | Optional | N/A | N/A | N/A
TYPELOG | Optional | Optional | Optional | Optional | Optional
U
The user ID required to access the DB2 database specified by the DB parameter, if applicable.
P
The password required for the user ID specified by the U parameter, if applicable.
NAME | OUT
The name of the generated schema extract file for ACTION=DELETE, EXTRACT, IMPORT or EXPORT. Do not specify a file extension. The default file extension is .hcodbs.
OUTLocal
Determines the location of the generated schema extract file. Schema extract files are stored in the \Schemas subdirectory of either of the following, depending on the value specified:
TRUE | Directory specified by the Local HCOSS Directory HCOSS option. Default.
FALSE | Directory specified by the Shared HCOSS Directory HCOSS option.
LOCATION
Sets the output directory for the schema extract file to:
LOCAL | Directory specified by the Local HCOSS Directory HCOSS option. Default.
SHARED | Directory specified by the Shared HCOSS Directory HCOSS option.
SCHEMA
The name of one or more valid DB2 schemas to extract. An asterisk (*) extracts all schemas in the catalog. Separate schema names with a comma (,).
TBS
The name of one or more valid DB2 tablespaces to extract. Separate tablespace names with a comma (,).
PATH
Specifies the directory to be used for IMPORT and EXPORT of schema extracts.
ROWCOUNT
Specifies the type of table row count information recorded:
ESTIMATE | Records the estimated table row count based on the schema statistics stored in SYSIBM.SYSTABLES. Use this option to improve performance. Default.
EXACT | Records both the estimated table row count and the actual row count as retrieved using a SELECT BIG-COUNT(*) query. Use this option to provide accuracy.
CATALOG
The name of the DB2 catalog schema. Defaults to SYSIBM.
TYPELOG
Sets the type of logging to perform. Defaults to the equivalent of the value specified for the Type of logging to do HCOSS option.

Example:

MFExtractSchemaInfo DB2=MVS91; OUT=LocalSchemaExtract; SCHEMA=MFIREX,SDI002; TYPELOG=FILE
MFExtractSchemaInfo DB2=MVS91; OUT=SharedSchemaExtract; OUTLocal=FALSE; SCHEMA=MFIREX%,SDI002
Parent topic: Command Line Reference
Related concepts
Extract Schema Tool
Related tasks
To extract DB2 schemas
To modify a schema extract file
Related reference
Extract Schema Tool Log Files
Extract Schema Tool Error Messages


MFObjectList command

Executes the HCOSS Define Lists tool from the command line.

Syntax:

MFObjectList S=schemaExtractFile;
             [SLocal={TRUE | FALSE};]
             OUT=objectListOutputFile;
             [OUTLocal={TRUE | FALSE};]
             [M=["]dataMappingFile["];]
             [SYSIBM={TRUE | FALSE};]
             [TYPE={TABLE | VIEW | ALL};]
             [SCHEMA=DB2Schema1[, DB2Schema2 ...];]
             [NAME=objectName;]
             [TYPELOG={CONSOLE | FILE | BOTH};]

Parameters:

S
The name of a schema extract file generated using the HCOSS Schema Extract tool. Do not specify a file extension.
SLocal
Determines the location of the schema extract file specified by the S parameter. Schema extract files are stored in the \Schemas subdirectory of either of the following, depending on the value specified:
TRUE | Directory specified by the Local HCOSS Directory HCOSS option. Default.
FALSE | Directory specified by the Shared HCOSS Directory HCOSS option.
OUT
The name of the generated object list file. Do not specify a file extension. The default file extension is .hcolst.
OUTLocal
Determines the location of the generated object list file. Object list files are stored in the \TargetLists subdirectory of either of the following, depending on the value specified:
TRUE | Directory specified by the Local HCOSS Directory HCOSS option. Default.
FALSE | Directory specified by the Shared HCOSS Directory HCOSS option.
M
Full path to and filename of the HCOSS data mapping file. If this specification contains spaces, enclose it in double quotes ("). Defaults to %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss\DataMappings.hcomap.
SYSIBM
Specifies whether or not to include the SYSIBM schema. Default is FALSE.
TYPE
Limits objects to tables only or views only. Default is ALL.
SCHEMA
The name of one or more valid DB2 schemas to include on the object list. Separate schema names with a comma (,). You may also use the % wild card character in schema names. Defaults to all schemas specified in the schema extract file.
NAME
Filters the object list to include only the specified DB2 table or view name. You may use the % wild card character in table and view names. Defaults to all table and view names.
TYPELOG
Sets the type of logging to perform. Defaults to the equivalent of the value specified for the Type of logging to do HCOSS option.
MFObjectList S=LocalSchemaExtract; OUT=LocalObjectList; SCHEMA=MFIREX%,SDI002; TYPELOG=FILE
MFObjectList S=SharedSchemaExtract; SLocal=FALSE; OUT=SharedObjectList; OUTLocal=FALSE; SCHEMA=MFIREX%,SDI002;
Parent topic: Command Line Reference
Related concepts
Define Lists Tool
Related tasks
To define an object transfer list
Related reference
Define Lists Tool Log Files
Define Lists Tool Error Messages


MFTestConversion command

Executes the HCOSS Compare Data tool from the command line.

Syntax:

MFTestConversion {X=["]compareDataTaskFile["] | IN=["]compareCommandsFile["]};
                 [XLocal={TRUE | FALSE};]
                 [INLocal={TRUE | FALSE};]
                 [DB2=DB2DataSource;]
                 [U1=DB2Userid;]
                 [P1=DB2Password;]
                 [SRV=SQLServerDataSource;]
                 [U2=SQLServerUserid;]
                 [P2=SQLServerPassword;]
                 [TYPELOG={CONSOLE | FILE | BOTH};]

Parameters:

X
The name of a compare data task file containing compare commands generated by the UI version of the Compare Data tool. Do not specify a file extension. The file extension for a compare data task file is .hcocpt. If the compare data task file name contains spaces, surround it with a set of double quotes ("). The location of a compare data task file is determined by the selection of either the Local or Shared button for the compare data task.
IN
A flat text input file containing HCOSS COMPARE commands designed to carry out a user-defined set of comparisons. You can code this file in any text editor. No filenaming convention is enforced for this file; however, if the file name contains spaces, surround it with a set of double quotes (").
XLocal
Specifies the location of the compare data task file. Compare data task files are stored in the \CompareTasks subdirectory of either of the following, depending on the value specified:
TRUE | Directory specified by the Local HCOSS Directory HCOSS option. Default.
FALSE | Directory specified by the Shared HCOSS Directory HCOSS option.
INLocal
Determines the location of the compare commands file. Compare commands files are stored in the \CompareTasks subdirectory of either of the following, depending on the value specified:
TRUE | Directory specified by the Local HCOSS Directory HCOSS option. Default.
FALSE | Directory specified by the Shared HCOSS Directory HCOSS option.
DB2
The name of a cataloged and registered DB2 data source. Required when using the IN parameter, and required when using the X parameter only to override the connection specified in the compare data task file.
U1
The user ID required to access the DB2 data source specified either by the DB2 parameter or within the data task file, if applicable, and if the user ID for the DB2 data source is not stored with the specified connection.
P1
The password required for the user ID specified by the U1 parameter, if applicable, and if the password for the user ID specified in the U1 parameter is not stored with the specified connection.
SRV
The name of a cataloged and registered SQL Server data source. Required when using the IN parameter, and required when using the X parameter only to override the connection specified in the compare data task file.
U2
The user ID required to access the SQL Server data source specified either by the SRV parameter or within the data task file. Not required when using Windows authentication. If not using Windows Authentication, this is required only if the user ID for the SQL Server data source is not stored with the specified connection.
P2
The password required for the user ID specified by the U2 parameter, if applicable, and if the password for the user ID specified in the U2 parameter is not stored with the specified connection.
TYPELOG
Sets the type of logging to perform. Defaults to the equivalent of the value specified for the Type of logging to do HCOSS option.

Comment:

Parameters may be given in any order.

Example:

MFDataTransferCtlr DB2=MVS91; SRV=HCODemo; X=LocalCompareData; TYPELOG=FILE
MFDataTransferCtlr DB2=MVS91; SRV=HCODemo; X=SharedCompareData; XLocal=FALSE
Parent topic: Command Line Reference
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
To run customized data comparisons
Related reference
Compare Data Tool Log Files
Compare Data Tool Error Messages


COMPARE Command File

Explains how to code a COMPARE command file to use with the MFTestConversion command, IN parameter.

Syntax:

USE DB2;
SELECT arguments;
USE SRV;
SELECT arguments;
COMPARE [integer ROWS] [SKIP COL integer1 [integer2 ...]]
[USE DB2;
SELECT arguments;
USE SRV;
SELECT arguments;
COMPARE [integer ROWS] [SKIP COL integer1 [integer2 ...]]
[...]]

Parameters:

USE DB2
Execute the following SQL SELECT command against the DB2 connection specified on the MFTestConversion command line.
USE SRV
Execute the following SQL SELECT command against the SQL Server connection specified on the MFTestConversion command line.
SELECT arguments
Any valid SQL SELECT statement returning a set of values to be compared. Each SELECT statement applies to the database specified in the USE statement that immediately precedes it. You must code at least one SELECT statement corresponding to the preceding USE DB2 and USE SQL statements respectively before coding a COMPARE statement. The returned values for both SELECT statements preceding a COMPARE statement should include the same list of columns in the same order to ensure success. Qualifiers for table names and column names can differ, depending on how the tables are defined in their respective databases.
COMPARE
With no arguments, compares all rows and all columns in the result sets for each preceding SELECT statement.
integer ROWS
Compare only the first integer rows, where integer represents any number greater than zero (0).
SKIP COL integer [integer ...]
Do not return compare information for each column number specified by integer, where integer represents any number greater than zero (0) and less than the number of columns in the SELECT list or 749; separate each specified integer with a space.

Comments:

Code a COMPARE command file using any text editor and save with the filename of your choice in either the directory specified by the Local HCOSS Directory or the directory specified by the Shared HCOSS Directory HCOSS option.

You can code multiple comparisons into a single COMPARE command file.

USE and COMPARE commands and their respective arguments are not case sensitive.

SQL SELECT statements might be case sensitive depending on how the database handles case sensitivity.

You can combine the ROWS and SKIP COL options.

Synonyms for COL are:
  • COLUMN
  • COLUMNS
  • COLS

Examples:

Compare all returned tables and rows:
USE DB2;
SELECT * FROM EMPINFO2;
USE SRV;
SELECT * FROM EMPINFO2;
COMPARE;
Compare a limited number of rows:
USE DB2;
SELECT * FROM EMPINFO2;
USE SRV;
SELECT * FROM EMPINFO2;
COMPARE 10 ROWS;
Skip certain columns:
USE DB2;
SELECT * FROM EMPINFO2;
USE SRV;
SELECT * FROM EMPINFO2;
COMPARE SKIP COLS 3 5 15;
Compare a limited number of rows and skip certain columns:
USE DB2;
SELECT * FROM EMPINFO2;
USE SRV;
SELECT * FROM EMPINFO2;
COMPARE 10 ROWS SKIP COLS 3 5 15;
Include more than one comparison in a single COMPARE command file:
USE DB2;
SELECT * FROM EMPINFO2;
USE SRV;
SELECT * FROM EMPINFO2;
COMPARE 10 ROWS SKIP COLS 3 5 15;
USE DB2;
SELECT * FROM EMPINFO3;
USE SRV;
SELECT * FROM EMPINFO3;
COMPARE;
Parent topic: Command Line Reference


DSN command

Executes the DSN Bind utility, which performs schema updates as necessary and executes the commands contained in an HCOSS bind script file.

Syntax

DSN SYSTEM(SQLServerConnection) @"bindScriptFile"
[ASUSER(userID.password)]

Parameters

SQLServerConnection | The name of an established connection to a SQL Server database.
bindScriptFile | The full path to and filename of the bind script (.hcodsn) file that contains the commands you want to execute.1
userID | The user ID required to log onto your SQL Server database. Enclose in double quotes (") if the user ID contains non-alphanumeric characters.2
password | The password required to log onto your SQL Server database. Enclose in double quotes (") if the password contains non-alphanumeric characters.2

1 For a listing of commands that are valid in HCOSS bind script files, see the topic Bind Script Commands.

2 The level of database access permissions required by these login credentials can vary. For details, see the topic DSN Bind Utility.

Comments

  • DSN.exe is in the %ProgramFiles(x86)%\Micro Focus\Enterprise Server\bin directory.
  • Execute DSN.exe from a command prompt in the %ProgramFiles(x86)%\Micro Focus\Enterprise Server\bin directory.
  • When deploying to a remote server, you can optionally execute DSN.exe on your deployment server instead of your development server; however, to do this you must have appropriate permissions on the deployment server machine.
  • Create the bind script file either with the Manage Packages and Plans tool, or manually in a text editor.
  • If you omit the ASUSER parameter, DSN uses Windows authentication, prompting you for a username and password if it fails.
Parent topic: Command Line Reference
Related concepts
DSN Bind Utility
Binding Applications
Migration Scenarios
Deploying Native Applications
Related tasks
To bind from the command line
To manually code a bind script file


Required DB2 Catalog Tables

The login credentials used to connect to the mainframe DB2 database must grant read access to the following DB2 system catalog tables:

Note: In addition to these DB2 Catalog table permissions, the Microsoft OLE DB provider must be properly configured with mainframe DB2. Please see DB2 Database Migration Process for additional information.
Object Type | DB2 System Catalog Table
tables, columns | SYSTABLES, SYSCOLUMNS, SYSSEQUENCES
indexes | SYSINDEXES, SYSKEYS
constraints (relational, check, key) | SYSCHECKS, SYSCHECKDEP, SYSCHECKS2, SYSCONSTDEP, SYSTABCONST, SYSKEYCOLUSE, SYSRELS, SYSFOREIGNKEYS
views | SYSVIEWS, SYSVIEWDEPENDENCY
Parent topic: Reference
Related concepts
Extract Schema Tool
DB2 Database Migration Process
Related tasks
To extract DB2 schemas
To modify a schema extract file


DB2 to SQL Server Conversion Reference

  • Date and Time Data Types
    The default formats for DB2 and SQL Server date and time specifications.
  • Default Data Type Mappings
    The default mappings HCOSS uses to convert DB2 data types into SQL Server data types.
  • Default SQL Name Mappings
    The default mappings HCOSS uses to convert DB2 functions and special registers to SQL Server equivalents.
  • Default SQLCODE Mappings
    The default mappings HCOSS uses to convert DB2 SQLCODEs into SQL Server SQLCODEs.
  • DSNTIAR and DSNTIAC
    Converts SQL return codes to character-string messages.
Parent topic: Reference


Date and Time Data Types

The default formats for DB2 and SQL Server date and time specifications.

These topics are included as a reference to assist you in determining conversion specifications for date and time data types going from DB2 to SQL Server.

  • Mainframe Date and Time Data Types
  • SQL Server Date and Time Data Types
Parent topic: DB2 to SQL Server Conversion Reference


Mainframe Date and Time Data Types

The mainframe date and time data types are date, time and timestamp. Date has a range from 0001-01-01 to 9999-12-31. Time has a range from 00:00:00 to 23:59:59. The special value 24:00:00 is equivalent to 24:00:00. The range of datetime is 1-1-1 00:00:00.000000 to 9999-12-31 23:59:59.999999.

Character string representation of date values

Format Name | Abbreviation | Date Format | Example
International Standards Organization | ISO | yyyy-mm-dd | 1987-10-12
IBM USA Standard | USA | mm/dd/yyyy | 10/12/1987
IBM European Standard | EUR | dd.mm.yyyy | 12.10.1987
Japanese industrial standard Christian era | JES | yyyy-mm-dd | 1987-10-12
Installation-defined | LOCAL |  |

Character string representation of TIME values

Format Name | Abbreviation | Date Format | Example
International Standards Organization | ISO | hh.mm.ss | 13.30.05
IBM USA Standard | USA | hh:mm AM or PM | 1:30 PM
IBM European Standard | EUR | hh.mm.ss | 13.30.05
Japanese industrial standard Christian era | JES | hh:mm:ss | 13:30:05
Installation-defined | LOCAL |  |

Character string representation of timestamp values

The default format is yyyy-mm-dd-hh-hh.mm.ss.nnnnnn.

The ODBC/JDBC format is also accepted; this is yyyy-mm-dd hh:mm:ss.nnnnnn.

Parent topic: Date and Time Data Types


SQL Server Date and Time Data Types

SQL Server legacy data types are:
  • datetime
  • smalldatetime
However, these are not recommended for mainframe application migration. To facilitate migration, SQL Server 2008 added these data types:
Data Type | Range | Fractional Second Digits
date | 0001-01-01 to 9999-12-31 |
time | 00:00:00.0000000 to 23:59:59.9999999 | 0 to 7
datetime2 | 0001-01-01 00:00:00.0000000 to 9999-12-31 23:59:59.9999999 | 0 to 7
datetimeoffset |  |

SQL Server provides considerable flexibility in reading date and time data as character strings, only a subset that is most directly relevant for migrations is presented here.

Default output format

SQL Server outputs date, time and datetime values in the following formats: yyyy-mm-dd, hh:m:ss.nnnnnnn (n is dependent on the column definition) and yyyy-mm-dd hh:mm:ss.nnnnnnn (n is dependent on the column definition).

Character string representation of date values

Format Type | Date Format | Example
ANSI/ISO | yyyy-mm-dd | 1987-10-12
Alphabetic | The month is specified as a three character abbreviation or the full month name. | Apr 15 1996 15 Apr 1996 1996 Apr 15
Numeric | The month is specified as a number and the separator can be slash, hyphen or period. The order of day, month year parts can be changed by a TSQL SET DATEFORMAT or SET LANGUAGE statements. The initial order is determined from the default language for the login. The default format for us_english is mdy. The settings are stored in the table sys.syslanguages. | 15/04/1996 04.15.1996 1996-4-15

Character string representation of time values

SQL Server accepts time values in the following formats: 14:30, 14:30:20, 14:30:20:145943, 2 PM, 2:30 PM, 2:30:20 PM 2:30:20.145943 PM.

Character string representation of datetime values

SQL Server accepts datetime values in ISO 8601 and ANSI formats, which are: yyyy-mm-ddThh:mm:ss.nnnnnn and yyyy-mm-dd hh:mm:ss.nnnnnn, respectively.

Parent topic: Date and Time Data Types


Default Data Type Mappings

The default mappings HCOSS uses to convert DB2 data types into SQL Server data types.

DB2 Data Type | Encoding | Data Storage | SQL Server Data Type
BIGINT | All | None | BIGINT
BINARY | All | None | BINARY
BLOB | All | None | VARBINARY(MAX)
CHAR | All | For bit data | BINARY
CHAR | ASCII and EBCDIC | None | CHAR
CHAR | UNICODE | None | NCHAR
CLOB | ASCII | None | NVARCHAR(MAX)
CLOB | ASCII | For bit data | NVARCHAR(MAX)
CLOB | EBCDIC | For bit data | NVARCHAR(MAX)
CLOB | UNICODE | None | NVARCHAR(MAX)
CLOB | UNICODE | For bit data | NVARCHAR(MAX)
CLOB | EBCDIC | None | NVARCHAR(MAX)
DATALINK | All | None | VARCHAR(2083)
DATE | All | None | DATE
DBCLOB | All | None | NVARCHAR(MAX)
DECFLOAT | All | None | FLOAT(53)
DECIMAL | All | None | DECIMAL
DOUBLE | All | None | DOUBLE PRECISION
FLOAT | All | None | FLOAT
GRAPHIC | All | None | NCHAR
INT | All | None | INT
INTEGER | All | None | INTEGER
LONG VARCHAR | All | For bit data | VARCHAR(MAX)
LONG VARCHAR | All | None | VARCHAR(MAX)
LONG VARGRAPHIC | All | None | NVARCHAR(MAX)
LONGVARBIN | All | None | VARBINARY(MAX)
NUMERIC | All | None | NUMERIC
REAL | All | None | REAL
ROWID | All | None | BINARY(40)
SMALLINT | All | None | SMALLINT
TIME | All | None | TIME(0)
TIMESTMP | All | None | DATETIME2(6)
VARBIN | All | None | VARBINARY
VARCHAR | All | For bit data | BINARY
VARCHAR | All | None | VARCHAR
VARGRAPHIC | All | None | NVARCHAR
XML | All | None | XML
Parent topic: DB2 to SQL Server Conversion Reference


Default SQL Name Mappings

The default mappings HCOSS uses to convert DB2 functions and special registers to SQL Server equivalents.

DB2 Function/Special Register | SQL Server Equivalent | Is Function | Is Special Register
VARIANCE | VAR | Yes |
IFNULL | COALESCE | Yes |
VALUE | COALESCE | Yes |
ASCII_CHR | CHAR | Yes |
LCASE | LOWER | Yes |
REPEAT | REPLICATE | Yes |
SUBSTR | SUBSTRING |  |
UCASE | UPPER | Yes |
LN | LOG | Yes |
CURRENT CLIENT_APPLNAME | APP_NAME() |  | Yes
CURRENT CLIENT_USERID | SYSTEM_USER |  | Yes
CURRENT CLIENT_WRKSTNNAME | HOST_NAME() |  | Yes
CURRENT DATE | CONVERT(date,SYSDATETIME()) |  | Yes
CURRENT TIME | CONVERT(time(0), SYSDATETIME()) |  | Yes
CURRENT TIMESTAMP | CONVERT(datetime2(6), SYSDATETIME()) |  | Yes
CURRENT_DATE | CONVERT(date,SYSDATETIME()) |  |
CURRENT_TIME | CONVERT(time(0), SYSDATETIME()) |  |
CURRENT_TIMESTAMP | CONVERT(datetime2(6), SYSDATETIME()) |  |
CURRENT LC_CTYPE | CONVERT(char(50), SERVERPROPERTY('collation')) |  | Yes
CURRENT_LC_CTYPE | CONVERT(char(50), SERVERPROPERTY('collation')) |  |
CURRENT LOCALE LC_CTYPE | CONVERT(char(50), SERVERPROPERTY('collation')) |  | Yes
CURRENT SCHEMA | CONVERT(varchar(128), SCHEMA_NAME()) |  | Yes
CURRENT_SCHEMA | CONVERT(varchar(128), SCHEMA_NAME()) |  |
CURRENT SERVER | CONVERT(char(16), SERVERPROPERTY('servername')) |  | Yes
CURRENT SQLID | USER |  | Yes
SESSION_USER | USER |  |
TRAN | "TRAN" |  |
APPLICATION | "APPLICATION" |  |
ORDER | "ORDER" |  |
DIGITS | dbo.digits | Yes |
LENGTH | DATALENGTH | Yes |
LPAD | dbo.LPAD | Yes |
RPAD | dbo.RPAD | Yes |
Parent topic: DB2 to SQL Server Conversion Reference


Default SQLCODE Mappings

The default mappings HCOSS uses to convert DB2 SQLCODEs into SQL Server SQLCODEs.

DB2 SQLCODE Value | SQL Server SQLCODE Value | SQLSTATE Value
-2601 | -803 | 23505
-19519 | -501 | 24501
-19516 | -502 | 24502
-2714 | -601 | 42710
-207 | -204 | 42704
-208 | -204 | 42704
Parent topic: DB2 to SQL Server Conversion Reference


DSNTIAR and DSNTIAC

Converts SQL return codes to character-string messages.

Syntax

CALL 'DSNTIAR' USING comm-area
                     error-message
                     error-rec-length

or, for CICS applications:

CALL 'DSNTIAC' USING comm-area
                     error-message
                     error-rec-length

Parameters

comm-area | The program's Commarea, usually SQLCA. At run time, the SQLCODE field in the SQLCA structure should contain the code from which DSNTIAR/DSNTIAC generates the character-string message.
error-message An array of records of size error-rec-length used to store error message output. The two components of the error-message array are:

error-length

Containing an integer greater than or equal to 240, indicating the length of the second element, error-text.

error-text

Containing the text of the message. Generally this message is defined as an array of strings, each having a length of error-rec-length, and occurring n times so that error-length is the larger of 240 and error-rec-length * n.

error-rec-length | An integer between 71 and 241, indicating the logical record length of output messages. If the error-message length exceeds the length defined for error-rec-length, the message is stored in several logical records.

Return Codes

The following table shows the return codes that result from calling the DSNTIAR or DSNTIAC utility.

Code | Description
0 | Successful execution.
4 | More data is available than can fit into the provided message area.
8 | The error record length is not within acceptable limits, i.e., 72 <= error-rec-length <= 240.
12 | The message area was not large enough. Message length was >= 240.
16 | Error in message routine.

Example

01 ERROR-MESSAGE.
     02 ERROR-LENGTH PIC S9(4) COMP VALUE +288.
     02 ERROR-TEXT PIC X(72) OCCURS 4 TIMES.
 77 ERROR-REC-LENGTH PIC S9(9) COMP VALUE +72.
    ...
     CALL 'DSNTIAR' USING SQLCA ERROR-MESSAGE ERROR-REC-LENGTH
Parent topic: DB2 to SQL Server Conversion Reference


Bind Script Commands

The following mainframe DSN commands are supported in bind script files and as input to JCL:
DSN Command | Supported Parameters
BIND PACKAGE | ACTION, MEMBER, LIBRARY, PKLIST, QUALIFIER, FLAG1
BIND PLAN | ACTION, MEMBER, LIBRARY, PKLIST, QUALIFIER, FLAG1
FREE PACKAGE | FLAG
FREE PLAN | FLAG
REBIND PACKAGE2 | QUALIFIER, FLAG, DYNAMICRULES1
REBIND PLAN 2 | PKLIST, QUALIFIER, FLAG, DYNAMICRULES 1
END

1 HCOSS ignores any other parameters present on the command line and issues a warning for each ignored parameter.

2 You can specify this in a bind script file you create manually; however, you cannot generate this command using the Manage Packages and Plans tool.

Note: For complete information on the use of these DSN commands including syntax, see the IBM DB2 documentation for DSN commands and subcommands available on the IBM Web site.
Parent topic: Reference
Related concepts
DSN Bind Utility
Binding Applications
Related tasks
To bind from the command line
To manually code a bind script file


Messages

Lists the error messages and other non-error messages that are produced by HCOSS tools.

  • Compare Data Tool Error Messages
  • Define Lists Tool Error Messages
  • Extract Schema Tool Error Messages
  • Generate DDL Tool Error Messages
  • Manage Connections Tool Error Messages
  • Transfer Data Tool Error Messages
Parent topic: Reference


Compare Data Tool Error Messages

This topic describes the error messages that are related to the Compare Data tool.

Error Message | Description or Cause | Resolution
A shared task cannot have a local transfer list | A shared task must associate a shared transfer list. | Make sure the shared radio button is checked for the transfer list.
Build Query failed | Build customized query by OpenESQL failed. | Make sure the source database connection is still open.
Command file is invalid or was not found | The file does not exist in the specified folder; or the file contains syntax errors. | Make sure the file exists and has correct syntax in its content.
Compare list file is empty | Compare list file has no meaningful content. | Add the desired content to the file.
Connection failed | Connection to either source database or destination database failed. | Make sure the user ID and password are correct.
Data comparison terminated for this table, error count exceeds mismatch limit | Error count exceeds the mismatch limit. | Check the mismatch errors to figure out which table causes the failure.
Data comparison test FAILED! | Data comparison test failed due to unmatched rows or columns. | Make sure the data in both source table and destination table are of the same set.
Data for following column does not match | The values of data in the two databases do not match. | Check if the data tables contain the same set of data in terms of rows, columns and ordering
Error in writing to file | Error in writing a task to XML file. | Check task name or path for illegal characters.
Execution Error | Execution of compare data failed due to connection failure. | Check database connections.
File Access Violation | Either READ or WRITE permission is not granted to the user. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user file access.
Following required parameter is missing | A required command line parameter is missing. | Provide the required parameter.
Invalid command line parameter | The specified parameter value is empty or out of range. | Assign a proper value to the parameter.
Invalid command line syntax | Some parameter names are incorrect. | Use the correct parameter names.
Invalid Data Source Name | The name of the data source or data destination is empty. | Add the name of the data source or data destination to the command line argument.
Invalid number of arguments | The command line has no arguments. | Add the required arguments to the command line.
Invalid target object list | The XML target list file has syntax errors. | Check the target list file content or try regenerating the target list.
No task name is set | No task name is set on GUI. | Select the desired task name on GUI.
Number of result set columns do not match | The number of table columns in the destination database does not match the corresponding one in the source database. | Check the DDL generation script.
Number of result set rows do not match | The number of rows in the destination table does not match that in the source table. | Rerun the Transfer Data tool.
Query Failed = … | Execution of the query failed. | Check query syntax, database connection, and database access permission.
The destination DSN is not found | The destination DSN is not set or it is not defined. | Specify an existing connection or create one if the connection you want to use does not exist.
The process does not have the READ permission to the file | The process does not have READ permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission.
The process does not have the WRITE permission to the file | The process does not have WRITE permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission.
The source DSN is not found | The source DSN is not set, or it is not defined. | Set the source DSN or create one if it does not exist.
The transfer list is not found in the directory | The transfer task file does not exist in the specified path. | Make sure the specified file exists in the path; or the file name is correct.
Unable to read list file | The transfer list file is corrupted. | Check the file content for syntax errors.
Parent topic: Messages
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
To run customized data comparisons
Related reference
MFTestConversion command
Compare Data Tool Log Files


Define Lists Tool Error Messages

This topic describes the error messages that are related to the Define Lists tool.

Error Message | Description or Cause | Resolution
An unexpected error has occurred. Please report the following error to Micro Focus Support: | A generic error flag followed by a specific message. | See the following specific message for information.
Invalid XML schema input file | Errors in XML schema of the schema extract file. | Check the schema extract file (.hcodbs).
No schema files found. You must have at least one schema file to create object lists | No schema files in the specified directory. | Create schema files in the directory.
The process does not have the READ permission to the file | The process does not have READ permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission on the file.
The process does not have the WRITE permission to the file | The process does not have WRITE permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission on the file.
Unable to delete list file: | Unable to delete the specified list file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user DELETE permission on the file.
Unable to read list file: | Unable to read the specified list file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission on the file.
Unable to write list file: | Unable to write the specified list file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission on the file.
Parent topic: Messages
Related concepts
Define Lists Tool
Related tasks
To define an object transfer list
Related reference
MFObjectList command
Define Lists Tool Log Files


Extract Schema Tool Error Messages

This topic describes the error messages that are specific to the Extract Schema tool.

Error Message | Description or Cause | Resolution
Connection no longer open - processing terminated. Please re-select Schemas and try again | Connection time out. | Re-select the schemas (as to reconnect).
Could not open database connection | Either the database is not available or the connection parameters have errors. | Check the database availability, permission, network connectivity, and parameters in the connection string.
Error inserting in SysConsDep | Error in accessing table SYSIBM. SysConsDep in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysChkConstraints | Error in accessing table SYSIBM.SYSCHECKS in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysChkDepConstraints | Error in accessing table SYSIBM.SYSCHECKDEP in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysColumns | Error in accessing table SYSIBM. SysColumns in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysKeyColConstraints | Error in accessing table SYSIBM.SYSKEYCOLUSE in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysIndexes | Error in accessing table SYSIBM. SysIndexes in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysIndexCols | Error in accessing table SYSIBM.SYSKEYS in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysRelConstraints | Error in accessing table SYSIBM.SYSRELS in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysRelFkConstraints | Error in accessing table SYSIBM.SYSFOREIGNKEYS in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysTables | Error in accessing table SYSIBM. SysTables in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysTblConstraints | Error in accessing table SYSIBM.SYSTABCONST in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysViews | Error in accessing table SYSIBM. SysViews in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysViewDep | Error in accessing table SYSIBM. SysViewDep in DB2. | See the IBM SQL Message reference for the SQL error reported.
Invalid command line parameter | The specified parameter value is empty or out of range. | Assign a proper value to the required parameter.
Invalid Data Source Name | The name of the data source or data destination is empty. | Add the name of the data source or data destination to the command line argument.
Parent topic: Messages
Related concepts
Extract Schema Tool
Related tasks
To extract DB2 schemas
To modify a schema extract file
Related reference
MFExtractSchemaInfo command
Extract Schema Tool Log Files


Generate DDL Tool Error Messages

This topic describes the error messages that are related to the Generate DDL tool.

Error Message | Description or Cause | Resolution
An unexpected error has occurred. Please report the following error to Micro Focus Support: | A generic error flag followed by a specific message. | See the following specific message for information.
Commit exception type: | Error in commit of DDL generation. | See the following message for details.
Connection failed | The target database connection failed. | Make sure the user ID and password correct.
Encountered problem reading source database schema | Error in reading the schema file. | See the preceding message for details.
Encountered problem during file/path checks | Error in the specified file name or path. | Check the specified file name and path.
Encountered problem reading XML mappings | Error in reading the mapping file. | Check the specified file name and path.
Encountered problem writing DDL command file | Error in writing the DDL file. | Check the file folder existence and WRITE permission.
Following required parameter is missing | A required parameter is not provided | Provide the specified parameter value
Invalid command line parameter | The specified parameter value is empty or out of range. | Assign a proper value to the parameter.
Invalid number of arguments | The command line has no arguments. | Add the required arguments to the command line.
Invalid DDL output directory | Error in creating the DDL file directory. | Check the file directory existence and WRITE permission.
Invalid XML mapping input file | Error in reading the DDL file. | Check the file existence and READ permission.
Invalid XML schema input file | Error in reading the schema file. | Check the file existence and READ permission.
No list files found. You must have at least one list file to create scripts. | The original list file has been deleted or renamed. | Recreate the list file or delete the current task.
Rollback exception type: | Error in rollback of DDL generation. | See the message for details.
The process does not have the READ permission to the file | The process does not have READ permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission.
The process does not have the WRITE permission to the file | The process does not have WRITE permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission.
Unable to create DDL output file | Error in creating the DDL file. | Check the file directory existence and WRITE permission.
Unable to create export file: | Unable to create the specified export file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission on the directory.
Unable to delete export file: | Unable to delete the specified export file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user DELETE permission on the file.
Unable to delete task file: | Error in deleting the task file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user DELETE permission.
Unable to read list file: | Unable to read the specified list file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission on the file.
Unable to read script file: | Unable to read the specified script file. | Check the file existence. Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission on the file.
Unable to return to previous task file | Unable to set the previous task. The previous file is either missing or renamed. | Recreate the task file.
Unable to write list file: | Unable to write the specified script file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission on the directory.
Parent topic: Messages
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL
Related reference
MFDDLConverter command
Generate DDL Tool Log Files


Manage Connections Tool Error Messages

This topic describes error messages that are specific to the Manage Connections tool.

Error Message | Description or Cause | Resolution
32-bit ADO.NET connection failed | The specified 32-bit ADO.NET connection failed. | Check the connection parameters.
32-bit ODBC connection failed | The specified 32-bit ODBC connection failed. | Check the connection parameters.
64-bit ADO.NET connection failed | The specified 64-bit ADO.NET connection failed. | Check the connection parameters.
64-bit ODBC connection failed | The specified 64-bit ODBC connection failed. | Check the connection parameters.
(A connection) already exists and will not be imported | A warning message. | It can be ignored.
(A connection) cannot be imported. | An existing connection cannot be imported due to unsupported provider type. | Redefine the connection using a supported provider type.
An existing connection was found and no action was taken. If you wish to add or update an existing connection, please specify the FORCE=TRUE parameter. | An existing connection cannot be overwritten. | The user may choose to set the parameter FORCE=TRUE to overwrite, or do nothing.
An unexpected error has occurred. Please report the following error to Micro Focus Support: |  |
Following required parameter is missing | A required parameter is not provided. | Provide the specified parameter value.
Invalid command line parameter | The specified parameter value is empty or out of range. | Assign a proper value to the required parameter.
Invalid connection mode | The connection mode parameter “MODE” has no value. | Assign a value to the parameter.
Invalid connection name | The connection name parameter “DSN” has no value. | Assign a value to the parameter.
Invalid connection provider | The connection provider parameter “PROVIDER” has no value. | Assign a value to the parameter.
Invalid connection provider type | The connection provider type parameter “PTYPE” has no value. | Assign a value to the parameter.
Invalid connection save ADO.NET password flag | The connection save ADO.NET password flag parameter “ADOSAVEP” has no value. | Assign a value to the parameter.
Invalid connection server type | The connection server type parameter “STYPE” has no value. | Assign a value to the parameter.
Invalid connection type | The connection type parameter “CTYPE” has no value. | Assign a value to the parameter.
Invalid number of arguments | The command line has no arguments. | Add the required arguments to the command line.
The connection name specified already exists. Please provide a unique connection name. | The new connection name conflicts with an existing one. | Use a different name for the new connection.
The process does not have the WRITE permission to the file | The process does not have WRITE permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission.
Unable to list SQL Server instances | Unable to list SQL Server instances in the local area network. | Check the network connectivity.
Unable to write DSN tracking file | XML schema error. | Contact Micro Focus support.
Validation of command line parameters failed | Some of the command line parameters have syntax errors. | Correct the syntax errors by following the sample format provided in the command line usage documentation topic.
Parent topic: Messages
Related reference
Manage Connections Tool Log Files


Transfer Data Tool Error Messages

This topic describes the error messages that are related to the Transfer Data tool.

Error Message | Description or Cause | Resolution
A shared task cannot have a local transfer list | A shared task must associate a shared transfer list. | Make sure the shared radio button is checked for the transfer list.
A wrong row is selected | A wrong row is selected when updating the customization. | Make sure the last changed row is selected/highlighted.
Connection failed | Source or destination connection failed. | Make sure the user ID and password correct.
Deletion result: Failure | The user does not have the permission of DELETE for the table or database. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user permission of DELETE.
(DSN’s provider) is not an OLE DB Provider | The underlying database provider is not of OLE DB type. | Recreate the DSN using the recommended Microsoft OLE DB provider.
Error in writing to file | Error in writing a task to XML file. | Check the task name and path for illegal characters.
File Access Violation | Either READ or WRITE permission is not granted to the user. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user file access.
Invalid command line parameter | The specified parameter value is empty or out of range. | Assign a proper value to the parameter.
Invalid Data Source Name | The name of the data source or data destination is empty. | Add the name of the data source or data destination to the command line argument.
Invalid number of arguments | The command line has no arguments. | Add the required arguments to the command line.
Invalid target object list | Syntax error. There is no “=” operator. | Add an “=” operator.
No query is selected for customization | An action button is clicked before a row of query is selected for customization. | Make sure the row is highlighted first.
No task name is set | No task name is set on GUI. | Select the desired task name on GUI.
SSIS package execution result: Failure | Data in the source database is not accessible. Data type mapping is incompatible. | Make sure the data accessible for SELECT statement. Check the version of SQL Server Native Client provider. It should be 10.x or above.
SSIS package validation result: Failure | Either the source or destination connection fails. | Check the connection(s).
Target table does not exist | The target table in the destination database has not been created. | Create the table in the destination database.
The destination DSN is not found | The destination DSN is not set or it is not defined. | Specify an existing connection or create one if the connection you want to use does not exist.
The process does not have the READ permission to the file | The process does not have READ permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission.
The process does not have the WRITE permission to the file | The process does not have WRITE permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission.
The source DSN is not found | The source DSN is not set, or it is not defined. | Set the source DSN or create one if it does not exist.
The transfer list is not found in the directory | The transfer task file does not exist in the specified path. | Make sure the specified file exists in the path; and the file name is correct.
There is no object list file in the location | No transfer list files in the specified “local” or “shared” folder. | Run through Define List tool again.
There is no table in the Data Transfer list | The data transfer task file contains no tables. | Add the desired tables to the task file.
Unable to read list file | Unable to read the transfer list file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission on the file.
Validation of command line parameters failed | Some of the command line parameters have syntax errors. | Correct the syntax errors by following the required format.
Workflow Error | The workflow is not in correct order. | Make sure the workflow in correct order.
Parent topic: Messages
Related concepts
Transfer Data Tool
Related tasks
To transfer data
To customize a transfer data task
Related reference
MFDataTransferCtlr command
Transfer Data Tool Log Files


Log Files

  • Manage Connections Tool Log Files
  • Extract Schema Tool Log Files
  • Define Lists Tool Log Files
  • Generate DDL Tool Log Files
  • Transfer Data Tool Log Files
  • Compare Data Tool Log Files
  • Manage Packages and Plans Tool Log Files
Parent topic: Reference


Manage Connections Tool Log Files

Log File Generation

The Manage Connections Tool creates one log file per GUI session.

File Location

logFileDir\Connections

where logFileDir is the value of the Directory to write log files to HCOSS option.

File Name

CONMAN-year-month-day-generatedTimestamp.log

where generatedTimestamp is a six- to eight-digit string representing the timestamp.

File Contents

  • Parameter validation
  • Connection checking
  • Add actions
  • Update actions
  • Delete actions
Parent topic: Log Files
Related reference
Manage Connections Tool Error Messages


Extract Schema Tool Log Files

Log File Generation

GUI Tool

The GUI version of the Extract Schema tool generates one log file per GUI session when you have set the Type of logging to do HCOSS option to either Write log messages just to file or Write log messages to both console and file.

MFExtractSchemaInfo Command

When running the Schema Extract tool from the command line, HCOSS generates a log file when you have set the TYPELOG directive to either FILE or BOTH, and when TYPELOG is not specified, defaults to the value of the Type of logging to do HCOSS option.

File Location

logFileDir\Schemas

where logFileDir is the value of the Directory to write log files to HCOSS option.

File Name

SCHEMCAP-year-month-day-generatedTimestamp.log

where generatedTimestamp is a six- to eight-digit string representing the timestamp.

File Contents

  • Processing information
  • Warning messages
  • Error messages
Parent topic: Log Files
Related concepts
Extract Schema Tool
Related tasks
To extract DB2 schemas
To modify a schema extract file
Related reference
MFExtractSchemaInfo command
Extract Schema Tool Error Messages


Define Lists Tool Log Files

Log File Generation

GUI Tool

The GUI version of the Define Lists tool generates one log file per GUI session when you have set the Type of logging to do HCOSS option to either Write log messages just to file or Write log messages to both console and file.

MFObjectList Command

When running the Define Lists tool from the command line, HCOSS generates log files when you have set the TYPELOG directive to either FILE or BOTH, and when TYPELOG is not specified, defaults to the value of the Type of logging to do HCOSS option.

File Location

logFileDir\TargetLists

where logFileDir is the value of the Directory to write log files to HCOSS option.

File Name

TLMAN-year-month-day-generatedTimestamp.log

where generatedTimestamp is a six- to eight-digit string representing the timestamp.

File Contents

  • Processing information
  • Warning messages
  • Error messages
Parent topic: Log Files
Related concepts
Define Lists Tool
Related tasks
To define an object transfer list
Related reference
MFObjectList command
Define Lists Tool Error Messages


Generate DDL Tool Log Files

Log File Generation

GUI Tool

The GUI version of the Generate DDL tool generates one log file per GUI session when you have set the Type of logging to do HCOSS option to either Write log messages just to file or Write log messages to both console and file.

MFDDLConverter Command

When running the Generate DDL tool from the command line, HCOSS generates log files when you have set the TYPELOG directive to either FILE or BOTH, and when TYPELOG is not specified, defaults to the value of the Type of logging to do HCOSS option.

File Location

logFileDir\DDLTasks

where logFileDir is the value of the Directory to write log files to HCOSS option.

File Name

GUI Tool

SCHEMMIG-year-month-day-generatedTimestamp.log

where generatedTimestamp is a six- to eight-digit string representing the timestamp.

File Contents

  • Parameter validation
  • Processing information
  • Object totals

    In some cases, when HCOSS encounters certain behavioral differences between DB2 and SQL Server, the total number of objects processed can exceed the original count of DB2 objects. For example, DB2 v7 and v8 support a primary key with no primary index. However, all primary keys in SQL Server, when defined, automatically create an associated index. In that case, you could have an extra index object in the SQL Server DDL. The opposite is true as well.

    Note: XML indexes are not currently supported by the DDL Converter tool. XML indexes existing in the DB2 database are not created in the DDL, nor are columns that are part of a index and are also mapped to the SQL Server XML data type. This is true even if the originating DB2 index and column are not of XML type.
  • Conversion information

    Where DB2 and SQL Server database formats have differences, HCOSS logs suggestions at each stage of operation as to possible workarounds.

Parent topic: Log Files
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL
Related reference
MFDDLConverter command
Generate DDL Tool Error Messages


Transfer Data Tool Log Files

Log File Generation

GUI Tool

The GUI version of the Transfer Data tool generates one HCOSS log file per GUI session when you have set the Type of logging to do HCOSS option to either Write log messages just to file or Write log messages to both console and file. It also generates one SSIS log file for each table processed, regardless of the Type of logging to do setting.

MFDataTransferCtlr Command

When running the Transfer Data tool from the command line, HCOSS generates a transfer data log file when you have set the TYPELOG directive to either FILE or BOTH, and when TYPELOG is not specified, defaults to the value of the Type of logging to do HCOSS option. It also generates one SSIS log file for each table processed, regardless of the TYPELOG setting.

File Locations

Transfer Data Log Files

logFileDir\DataTasks

where logFileDir is the value of the Directory to write log files to HCOSS option.

SSIS Log Files

genHCOSSFiles\DataTasks

where genHCOSSFiles is the value of either the Local HCOSS Directory or Shared HCOSS Directory HCOSS option, depending on whether your data task is local or shared.

File Name

Transfer Data Log File

DATTRANS-year-month-day-generatedTimestamp.log

where generatedTimestamp is a six- to eight-digit string representing the timestamp.

SSIS Log Files

[SQLServerSchemaName]_[TableName]_RunTimeLog.log

File Contents

Transfer Data Log File

The HCOSS log file contains messages generated during package execution, including:
  • Package validation
  • Execution
  • Progress
  • Errors
  • Warnings
  • Diagnostics

SSIS Log File

The SSIS log file contains progress and error messages generated during the building of a package.

Parent topic: Log Files
Related concepts
Transfer Data Tool
Related tasks
To transfer data
To customize a transfer data task
Related reference
MFDataTransferCtlr command
Transfer Data Tool Error Messages


Compare Data Tool Log Files

Log File Generation

GUI Tool

The GUI version of the Compare Data tool generates one log file per GUI session when you have set the Type of logging to do HCOSS option to either Write log messages just to file or Write log messages to both console and file.

MFTestConversion Command

When running the Compare Data tool from the command line, HCOSS generates a log file when you have set the TYPELOG directive to either FILE or BOTH, and when TYPELOG is not specified, defaults to the value of the Type of logging to do HCOSS option.

File Location

logFileDir\CompareTasks

where logFileDir is the value of the Directory to write log files to HCOSS option.

File Name

DATACOMP-year-month-day-generatedTimestamp.log

where generatedTimestamp is a six- to eight-digit string representing the timestamp.

File Contents

  • Processing information
  • Warning messages
  • Error messages
Parent topic: Log Files
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
To run customized data comparisons
Related reference
MFTestConversion command
Compare Data Tool Error Messages


Manage Packages and Plans Tool Log Files

Log File Generation

The Manage Packages and Plans tool generates one log file per GUI session when you have set the Type of logging to do HCOSS option to either Write log messages just to file or Write log messages to both console and file.

File Location

logFileDir\BindTasks

where logFileDir is the value of the Directory to write log files to HCOSS option.

File Name

BINDTASKS-year-month-day-generatedTimestamp.log

where generatedTimestamp is an eight-digit string representing the timestamp.

File Contents

  • Processing information
  • Warning messages
  • Error messages
Parent topic: Log Files


User Interface Reference

  • Manage Connections
  • Extract Schema
  • Assess Data Migration
  • Generate SPD File tab
  • Define Lists
  • Generate DDL
  • Transfer Data
  • Compare Data
  • Manage Packages and Plans
  • Data Mappings tab
  • SQL Name tab
  • Customize SQLCode Mappings
  • Options
Parent topic: Reference


Manage Connections

  • Connection List tab
  • DB2 Connection tab
  • SQL Server Connection tab
  • Export tab
  • Import tab
  • Log Files tab
Parent topic: User Interface Reference


Connection List tab

Connection List
A list of all available connections.
Name
The data source name you specified for the connection when you created it.
Type
The type of database connection, SQL Server or DB2.
Status
The last known status of the connection:
Checking | HCOSS is checking the status of the connection
OK | Able to connect
Needs Repair | Unable to make the connection using the supplied information
Unknown | Shows for newly created or imported connections when your HCOSS Automatically Test Connections option is set to False, and before you Refresh the connection for the first time
New DB2 Connection
Switch to the DB2 Connection tab to create a new DB2 connection.
New SQL Server Connection
Switch to the SQL Server Connection tab to create a new SQL Server connection.
Edit
Switch to the SQL Server Connection or DB2 Connection tab, depending on the selected connection, where you can make changes to your connection specifications.
Remove
Remove the selected connection.
Repair
Repair a connection that reports Needs Repair in the Status column on the Connection List.
Refresh
Update information in the Status column for the selected connection.
Refresh All
Update the information in the Status column for all connections.
System
Create a system connection, and show only system connections on the Connections List grid.
User
Create a user connection, and show only user connections on the Connections List grid.
Encrypt ADO Connection Settings
Write ADO.NET connection specifications to appropriate .config files in encrypted format. In this version of HCOSS, this check box has no effect on the connection.
Enable Checking for New ODBC Drivers
When editing and repairing connections, HCOSS checks the current ODBC driver version and prompts you to upgrade if a more recent version is installed and available. Applies to System and User connection types only.
Parent topic: Manage Connections


DB2 Connection tab

Data Source Name
Type a name for this connection.
User ID
Type the user ID you want to use for your DB2 database login.
Password
Type the password you want to use for your DB2 database login.
Allow Saving ADO.NET Connection Password
Set HCOSS to remember your ADO.NET password. When unchecked, the system prompts you for a password each time you connect from other HCOSS tools.In this version of HCOSS, this check box has no effect on the connection.
Network Address
The IP address used on your network to connect to your mainframe DB2 database.
Network Port
The port number used to access your mainframe DB2 database.
Initial Catalog
The name of the catalog used by your DB2 database.
Package Collection
The name of the package collection your DB2 database connection uses to talk to mainframe DB2.
Test
Verify that the information you have specified on this tab is sufficient to create a working DB2 database connection.
Save
Create a DB2 ADO.NET connection based on the information you have specified on this tab.
Parent topic: Manage Connections


SQL Server Connection tab

ODBC Driver
Shows the name and version of the ODBC driver in use for the current connection. Visible for System and User connection types only.
Data Source Name
Type a name for this connection.
Integrated Windows Authentication
Automatically send your Windows user ID and password as login credentials for this connection.
Use SQL Server Login
Send the User ID and Password supplied in the corresponding fields as login credentials for this connection.
User ID
Type the user ID you want to use for your SQL Server login. This is required only when you have selected Use SQL Server Login.
Password
Type the password you want to use for your SQL Server login. This is required only when you have selected Use SQL Server Login.
Allow Saving ADO.NET Connection Password
Set HCOSS to remember your ADO.NET password. When unchecked, the system prompts you for a password each time you connect from other HCOSS tools. This check box applies only when you have selected Use SQL Server Login. In this version of HCOSS, this check box has no effect on the connection.
SQL Server Instance
Select a SQL Server instance from the drop-down list, or type the name of a SQL Server instance. Use . or (local) to specify your local machine.
Refresh
Refresh the list of available SQL Server instances.
Confirm Server
When you specify a SQL Server instance by typing into the SQL Server Instance field rather than selecting from the drop-down list, click this to confirm the specified instance and test its validity.
Use a database other than the default database: dbname
Activates the Database drop-down list, enabling you to specify an alternative database for this connection.
Database
Select a database from the drop-down list, which includes all SQL Server databases available for the login credentials you specified for this connection.
Test
Verify that the information you have specified on this tab is sufficient to create a working SQL Server connection.
Save
Create an ODBC and an ADO.NET SQL Server connection, each based on the information you have specified on this tab.
Parent topic: Manage Connections


Export tab

Select All
Select all entries listed on the connections grid.
Unselect All
Unselect all entries listed on the connections grid.
Name
The data source name you specified for the connection when you created it.
Type
The type of database connection, SQL Server or DB2.
Status
The last known status of the connection:
OK | The connection is established and working properly
Needs Repair | The connection is established but is not working properly
Unknown | Shows for newly created or imported connections when your HCOSS Automatically Test Connections option is set to False, and before you Refresh the connection for the first time
Export to file
The full path to and filename of an XML (.xml) file to which you want to save your connection information.
Export
Export the selected connections.
Parent topic: Manage Connections


Import tab

Import from file
The full path to and filename of an XML (.xml) file you want to import.
Read Available Connections
Loads all connections defined in the imported XML file into the connections grid.
Select All
Select all entries listed on the connections grid.
Unselect All
Unselect all entries listed on the connections grid.
Name
The name of the connection as specified by the <name> element in the imported XML file.
Connection String
The connection string required to create the connection, as specified in the <ConnectString> element of the imported XML file.
Import
Import the selected connections.
Progress
Shows the progress of the import process.
Parent topic: Manage Connections


Log Files tab

Log file path
Shows the full path to the folder containing your log files.
Log files
This grid lists each log file residing in the Log file path, in reverse chronological order.
Delete Selected
Delete the log files selected on the list.
Delete All
Delete all log files on the list.
Filter by
Select a filter to dictate the contents shown in the Log file contents window.
Log file contents
Shows the contents of the selected log file based on the selected filter.
Parent topic: Manage Connections
Parent topic: Extract Schema
Parent topic: Define Lists
Parent topic: Generate DDL
Parent topic: Manage Packages and Plans


Extract Schema

  • Schema Extract tab
  • Create New Schema Extract
  • Results tab
  • Log Files tab
Parent topic: User Interface Reference


Schema Extract tab

Select schema(s) to extract
List of schemas available in the DB2 database specified by the DB2 data source connection. The list includes schemas that contain one or more tables, views, stored procedures, or any combination of tables, views, and stored procedures.
Schema Extract Name
A name for the schema extract file.
Local
Sets the Extract Schema tool to save the generated schema extract file to the directory specified by the Local HCOSS Directory HCOSS option.
Shared
Sets the Extract Schema tool to save the generated schema extract file to the directory specified by the Shared HCOSS Directory HCOSS option.
DB2 Connection
The name of a DB2 data source connection.
Estimated using schema statistics
Records the estimated table row count using statistics last updated by the mainframe DB2 RUNSTATS utility. Use this option to improve performance.
Both Estimated and Actual (COUNT(*))
Records both the estimated table row count and the actual row count as retrieved using a SELECT BIG_COUNT(*) query. Use this option to provide accuracy.
New
Create a new schema extract file.
Revert
Removes all changes made on this tab, setting each field and control to its last saved setting.
Save
Saves changes made on this tab.
Delete
Deletes the schema extract file.
Extract
Extract the schemas selected on the Select Schema(s) to Extract list.
Import
Import a previously exported schema extract file.
Export
Copy the generated schema extract file to a specified directory so that it can be used to import the schema into the tool when the mainframe is not available.
Parent topic: Extract Schema
Related concepts
Extract Schema Tool
Related tasks
To extract DB2 schemas
To modify a schema extract file


Create New Schema Extract

Schema Extract Name
A name for the schema extract file.
Metadata/Catalog Schema Name
The name of a manually created schema containing views of the SYSIBM schema. Use this to enable access to SYSIBM tables without granting access to the catalog itself.
Parent topic: Extract Schema
Related concepts
Extract Schema Tool
Related tasks
To extract DB2 schemas


Results tab

Schema Extract Results
Shows the results of the schema extract process.
Parent topic: Extract Schema
Related concepts
Extract Schema Tool
Related tasks
To extract DB2 schemas
To modify a schema extract file


Assess Data Migration

  • Data Assessment Tasks tab
  • Create New Data Assessment Task dialog box
  • Results tab
Parent topic: User Interface Reference


Data Assessment Tasks tab

Available Assessments list
List of previously created data assessment tasks.
Available Assessments Local button
Show local transfer lists on the Available Transfer Lists list.
Available Assessments Shared button
Show shared transfer lists on the Available Transfer Lists list.
Associated Schema Extract list
List of local or shared extracted schemas created using the Extract Schema tool.
Associated Schema Extract Local button
Show local extracted schemas on the Associated Schema Extract list.
Associated Schema Extract Shared button
Show shared extracted schemas on the Associated Schema Extract list.
New
Create a new data assessment task.
Save
Save the data assessment task specified in the Available Assessments field.
Delete
Delete the data assessment task specified in the Available Assessments field.
DB2 Connection
The name of an existing DB2 connection.
Table List grid
Shows the information available in the extracted schema on a table-by-table basis.
Count-Type column
Select Actual to show the actual number of rows; select Estimated to show the estimated number of rows.
Transfer Option column
Change this from the default HCOSS to OTHER for tables you want to exclude from the schema extract files.
Update Row Count
Update the schema extract file with changed information from the Table list grid.
Save Options
Save the options as they appear on the Table list grid.
Export Report (txt)
Save the data assessment specifications as a text file.
Export Details (csv)
Export the data assessment specifications to a CSV file compatible with spreadsheet software.
Parent topic: Assess Data Migration


Create New Data Assessment Task dialog box

Name
A name for the new data assessment task.
Schema Extract
Lists the schema extract files available to associate with the new data assessment task.
Parent topic: Assess Data Migration


Results tab

Update Results
Shows any error messages generated while updating row count.
Parent topic: Assess Data Migration


Generate SPD File tab

Schema Extract File
Lists the available schema extract files, either local or shared, depending on the selected radio button.
Local
List local schema extract files.
Shared
List shared schema extract files.
Select procedures to generate
Lists the stored procedures found in the selected schema extract file.

Publish Post Deployment Script group

Note: These fields are enabled only when using a DATETIME2 parameter.
File Name
The full path to and file name of the post-deployment script. If the path or the filename contain spaces, enclose the entire string in quotes.
Namespace
The default namespace of the project.
Generate changes
Generate the required changes in the post-deployment script.

SPD group

File Name
The name of the generated SPD file.
Generate fixed-length parameters
Pass all parameters to the SQL CLR Stored Procedure definition routine as fixed length.
Add file to active project
Add the generated SPD file to the current project.
Generate
Generate the stored procedure definition (SPD) file.
Parent topic: User Interface Reference
Related concepts
Generate SPD File tool
Related tasks
To generate a stored procedure definition (SPD) file


Define Lists

  • Transfer Lists tab
  • Create New List dialog box
  • Log Files tab
Parent topic: User Interface Reference


Transfer Lists tab

Available Transfer Lists list
List of previously created local or shared transfer lists.
Available Transfer Lists Local button
Show local transfer lists on the Available Transfer Lists list.
Available Transfer Lists Shared button
Show shared transfer lists on the Available Transfer Lists list.
Associated Schema Extract list
List of local or shared extracted schemas created using the Extract Schema tool.
Associated Schema Extract Local button
Show local extracted schemas on the Associated Schema Extract list.
Associated Schema Extract Shared button
Show shared extracted schemas on the Associated Schema Extract list.
New
Create a new transfer list.
Save
Save the transfer list specified in the Available Transfer Lists field.
Delete
Save the transfer list specified in the Available Transfer Lists field.
Type
Filter the Available Objects list by Table, View, or both (all).
Schema
Filter the Available Objects list by schemas available in the specified extracted schema.
Name
Filter the Available Objects list by schema items (tables or views) available in the specified extracted schema. The items on this list are filtered by the Type and Schema specifications.
Available Objects
Lists the objects available for transfer, filtered by the values specified in the Type, Schema, and Name fields.
Selected Objects
Lists the objects selected for transfer. Gray rows show objects that are dependent on a selected object but were not necessarily selected from the Available Objects list. The number in the Seq column shows dependency relationships.
Add All
Add all objects on the Available Objects list to the Selected Objects list.
Add
Add selected items on the Available Objects list to the Selected Objects list. Objects dependent on selected objects are added automatically.
Remove
Remove selected objects from the Selected Objects list. Objects dependent on a selected object are removed automatically.
Remove All
Remove all objects from the Selected Objects list.
Revert
Set the Available Objects and Selected Objects lists back to their last saved state.
Parent topic: Define Lists
Related concepts
Define Lists Tool
Related tasks
To define an object transfer list


Create New List dialog box

Name
A name for the new transfer list.
Schema Extract
Lists the schema extract files available to associate with the new transfer list.
Parent topic: Define Lists
Related concepts
Define Lists Tool
Related tasks
To define an object transfer list


Generate DDL

  • DDL Tasks tab
  • Create New DDL Task dialog box
  • Customize DDL tab
  • Schema Mappings tab
  • Results tab
  • Log Files tab
Parent topic: User Interface Reference


DDL Tasks tab

Available Tasks list
List of previously created local or shared generated DDL tasks.
Available Tasks Local button
Show local DDL tasks on the Available Tasks list.
Available Tasks Shared button
Show shared DDL tasks on the Available Tasks list.
Associated Transfer List list
List of local or shared transfer lists created using the Define Lists tool.
Associated Transfer List Local button
Show local transfer lists on the Associated Transfer List list.
Associated Transfer List Shared button
Show shared transfer lists on the Associated Transfer List list.
New
Create a new DDL task.
Save
Save the DDL task specified in the Available Tasks field.
Revert
Set changed fields and controls back to their last saved state.
Delete
Delete the DDL task specified in the Available Tasks field.
Drop and create objects
The generated DDL drops and creates objects in the destination SQL Server database. Default.
Restore missing objects
The generated DDL restores missing objects in the destination SQL Server database.
Connection for Check
The name of the SQL Server connection you want to use to test DLL task specifications. This defaults to the SQL Server data source specified for the Data source to use for testing DDL HCOSS Option, if set.
Connection for Execute
The name of the SQL Server connection you want to use when executing the DDL. This defaults to the SQL Server data source specified for the Name of the current/default target data source HCOSS Option, if set.
Preserve mainframe text sort order
When checked, HCOSS populates coded character set identifiers (CCSIDs), preserving the mainframe text sort order. If unchecked, the sort order is the default SQL Server order specified for the database. Default is unchecked.
Check
Checks the DDL task specifications against the SQL Server data source specified as the Connection for Check, and takes you to the Results tab to view the results of the check.
Execute
Generates the DDL and then executes it against the SQL Server data source specified as the Connection for Execute, and takes you to the Results tab to view the results.
Customize
Takes you to the Customize DDL tab where you can customize the SQL generated for the DDL.
Schema Mappings
Takes you to the Schema Mappings tab where you can change the name of your SQL Server schema.
Export SQL Script
Save the SQL generated for the DDL as an SQL script.
Parent topic: Generate DDL
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL


Create New DDL Task dialog box

Name
The name of the new DDL task.
Transfer List
Lists the transfer lists available to associate with the new DDL task.
Parent topic: Generate DDL
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL


Customize DDL tab

Objects grid
Lists the schema objects available in the transfer list specified in the Associated Transfer List field on the DDL Tasks tab, in the sequence in which they appear on the transfer list.
Check All
Checks all schema objects listed on the Objects grid against a SQL Server data source and takes you to the Results tab to view the results of the check. To use this option, you must have a test SQL Server data source specified in the Data source to use for testing DDL field of your HCOSS Options.
Revert All
Removes all changes to SQL code made for all objects on the Objects grid, setting the code back to its last saved state. Once saved, you cannot revert your changes.
Save All
Saves all changes to SQL code made for all objects on the Objects grid. Once saved, you cannot revert your changes.
Generated DDL
Shows the DDL generated by default for the object selected on the Objects grid.
Customized DDL
Edit the default DDL code for the object selected on the Objects grid to customize the code generated into the DDL.
Revert
Removes all changes made to the SQL code in the Customized DDL field, setting the code back to its default state. Once saved, you cannot revert your changes.
Parent topic: Generate DDL
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL


Schema Mappings tab

DB2 Schema Name
Lists the DB2 schemas available in the transfer list specified in the Associated Transfer List field on the DDL Tasks tab.
SQL Schema Name
Lists the SQL schema name mapped to each corresponding DB2 schema name. Default SQL schema names are the same as their corresponding DB2 schema names.
Parent topic: Generate DDL
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL


Results tab

Attempted DDL Command(s)
Shows the DDL commands tested against the test SQL Server data source specified in the Data source to use for testing DDL field of your HCOSS Options, or executed using the connection specified in the Destination Connection field on the DDL Tasks tab.
SQL Server Results
Shows results for the executed commands.
Parent topic: Generate DDL
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL


Transfer Data

  • Transfer Data Tasks tab
  • Create New Transfer Data Task dialog box
  • Customize Transfer Data tab
  • Results tab
Parent topic: User Interface Reference


Transfer Data Tasks tab

Available Tasks list
List of previously created local or shared transfer data tasks.
Available Tasks Local button
Show local transfer data tasks on the Available Tasks list.
Available Tasks Shared button
Show shared transfer data tasks on the Available Tasks list.
Associated DDL Task list
List of local or shared DDL tasks created using the Generate DDL tool.
Associated DDL Task Local button
Show local DDL tasks on the Associated DDL Task list.
Associated DDL Task Shared button
Show shared DDL tasks on the Associated DDL Task list.
New
Create a new transfer data task.
Save
Save the transfer data task specified in the Available Tasks field.
Revert
Set changed fields and controls back to their last saved state.
Delete
Delete the transfer data task specified in the Available Tasks field.
Source Connection
The name of an existing DB2 connection.
Destination Connection
The name of an existing SQL Server connection.
Transfer
Execute the task and transfer the data.
Clear
Clear the data tables in the destination SQL Server database.
Customize
Takes you to the Customize Transfer Data tab where you can customize the transfer specifiations for individual tables.
One SSIS package for each table
Generate one SSIS package for each table specified in the transfer data task.
Single SSIS package for all tables
Generate a single SSIS package containing all of the tables specified in the transfer data task. In the generation process, each table receives a sequence number to differentiate it from other tables in the package.
Export
Export SSIS package or packages as specified by the selected radio button.
Parent topic: Transfer Data
Related concepts
Transfer Data Tool
Related tasks
To transfer data
To customize a transfer data task


Create New Transfer Data Task dialog box

Name
The name of the new transfer data task.
DDL Task
Lists the DDL tasks available to associate with the new transfer data task.
Parent topic: Transfer Data
Related concepts
Transfer Data Tool
Related tasks
To transfer data
To customize a transfer data task


Customize Transfer Data tab

Tables grid

Seq
The sequence in which each object is transferred from the DB2 database to the SQL Server database.
Schema
The names of schemas containing data to be transferred.
Name
The names of tables containing data to be transferred.
Buffer rows
The maximum number of rows that can be held in an individual buffer during the transfer.
Query
Perform the transfer by running a query against the SQL Server via the SSIS engine.

Transfer Task Options group

Fail on Error
The data transfer fails when it encounters an error.
Log Error Rows
The Transfer Data tool logs an error for each row or series of rows containing an error, based on the number specified in the Commit Size field.
Commit Size
When Log Error Rows is selected, this editable field shows the number of error rows to identify before committing to the log file. Default it 10.
Ignore Error
The Transfer Data Tool ignores all errors and continues transferring data.
Fire Triggers
When checked, HCOSS fires all defined triggers during the data transfer. Default is unchecked.
Check Constraints
When checked, SQL Server performs all defined checks during the data transfer. Default is unchecked.

WHERE/ORDER BY in SELECT group

Build WHERE
Use the other controls in this group to build an WHERE clause for the query that corresponds to the tables selected on the grid.
Build ORDER BY
Use the other controls in this group to build an ORDER BY clause for the query that corresponds to the tables selected on the grid.
Column
Lists the columns available for the tables selected on the grid.
Conditional Operator
Lists valid conditional operators you can use for this clause.
AND
Inserts an AND into the clause.
OR
Inserts an OR into the clause.
Value
A literal value to insert into the clause.
>
Move completed clauses to the Predicate or Sort Order box.
<
Remove the clause from the Predicate or Sort Order box.
Predicate or Sort Order
Shows the code for a completed clause.

Transfer List Actions group

Update
Updates the selected query with the WHERE or ORDER BY clause in the Predicate or Sort Order box.
Save All
Saves all changes made to all table queries on the Objects list. Once saved, you cannot revert your changes.
Revert
Removes all changes made to the table queries selected on the Objects list, setting them back to their last saved state. Once saved, you cannot revert your changes.
Revert All
Removes all changes made to all table queries on the Objects list, setting them back to their last saved state. Once saved, you cannot revert your changes.

Source Table Row Count group

Estimate using schema statistics
Estimate the row count by querying CARDF in SYSIBM.SYSTABLES. Use this option for optimal performance if your schema statistics have been recently updated. This is the default setting when you have not specified a WHERE clause.
Acutal using COUNT_BIG(*)
Directly query the row count by executing SELECT COUNT_BIG(*) FROM targetTable. This option provides an accurate count of the rows to be transferred. This is the default setting when you specify a WHERE clause. Large tables can degrade performance.

Data Transfer Actions group

Clear
Clear the data tables in the destination SQL Server database.
Transfer
Transfer the data.
Parent topic: Transfer Data
Related concepts
Transfer Data Tool
Related tasks
To transfer data
To customize a transfer data task


Results tab

Transfer Results
Shows the results of the data transfer process.
Parent topic: Transfer Data
Related concepts
Transfer Data Tool
Related tasks
To transfer data
To customize a transfer data task


Compare Data

  • Compare Data Tasks tab
  • Create New Compare Data Task dialog box
  • Customize Compare Data tab
  • Results tab
Parent topic: User Interface Reference


Compare Data Tasks tab

Available Tasks list
List of previously created local or shared compare data tasks.
Available Tasks Local button
Show local compare data tasks on the Available Tasks list.
Available Tasks Shared button
Show shared compare data tasks on the Available Tasks list.
Associated DDL Task list
List of local or shared DDL tasks created using the Generate DDL tool.
Associated DDL Task Local button
Show local DDL tasks on the Associated DDL Task list.
Associated DDL Task Shared button
Show shared DDL tasks on the Associated DDL Task list.
New
Create a new compare data task.
Save
Save the compare data task specified in the Available Tasks field.
Revert
Set changed fields and controls back to their last saved state.
Delete
Delete the compare data task specified in the Available Tasks field.
Source Connection
The name of an existing DB2 connection.
Destination Connection
The name of an existing SQL Server connection.
Compare
Execute the task to compare the data.
Customize
Takes you to the Customize Compare Data tab where you can customize the specifiations for making the comparison.
Parent topic: Compare Data
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
To run customized data comparisons


Create New Compare Data Task dialog box

Name
The name of the new compare data task.
DDL Task
Lists the DDL tasks available to associate with the new compare data task.
Parent topic: Compare Data
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
To run customized data comparisons


Customize Compare Data tab

Task Attributes group

Task Name
The name of the Compare Data task being customized.
List Name
The name of the data transfer list specified in the associated DDL task.
Location
The location of the data transfer list, local or shared.
Source Schemas and Tables
A tree view showing the tables available for comparison.

WHERE/ORDER BY in SELECT group

Table
Shows the table selected on the Source Schemas and Tables tree view.
Build WHERE
Use the other controls in this group to build an WHERE clause for the specified table.
Build ORDER BY
Use the other controls in this group to build an ORDER BY clause for the specified table.
Column
Lists the columns available for the specified table.
Conditional Operator
Lists valid conditional operators you can use for this clause.
AND
Inserts an AND into the clause.
OR
Inserts an OR into the clause.
Value
A literal value to insert into the clause.
>
Move completed clauses to Customized Query Pair.
<
Remove the clause from Customized Query Pair.
Predicate or Sort Order
Shows the code for a completed clause.
Customized Query Pair
SQL statements associated with the table(s) selected on the Source Schemas and Tables tree view and appropriate clauses as built in the WHERE/ORDER BY in SELECT group.

Compare List Actions group

Save All
Saves all changes made to tables on the tree view. Once saved, you cannot revert your changes.
Revert All
Removes all changes made to tables on the tree view, setting them back to their default state. Once saved, you cannot revert your changes.
Compare
Compare the data.
Parent topic: Compare Data
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
To run customized data comparisons


Results tab

Comparison Results
Shows the results of the compare data process.
Parent topic: Compare Data
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
To run customized data comparisons


Manage Packages and Plans

  • Bind Scripts tab
  • Bind Packages tab
  • Bind Plans tab
  • Free Packages tab
  • Free Plans tab
  • Results tab
  • Log Files tab
Parent topic: User Interface Reference


Bind Scripts tab

New
Create a new bind script file.
Open
Open an existing bind script file.
Save
Save the bind script file.
Save As
Save the bind script file under a new name.
Bind Script File
Full path to and name of the bind script file.
SQL Server Connection
The data source name for your SQL Server connection.
Bind Script Entries
The BIND PACKAGE and BIND PLAN commands in the bind script file.
New Package
Switch to the Bind Packages tab to create a new package in the SQL Server database by generating a BIND PACKAGE command for the bind script file, and executing the command.
New Plan
Switch to the Bind Plans tab to create a new plan in the SQL Server database by generating a BIND PLAN command for the bind script file, and optionally executing the command as well.
Edit
Switch to either the Bind Packages or the Bind Plans tab, depending on the selection, to modify the selected command and generate and execute the changes as a new BIND PACKAGE command, or generate and optionally execute the changes as a new BIND PLAN command.
Move Up
Reposition the selected bind script command to appear before the command listed just above it.
Move Down
Reposition the selected bind script command to appear after the command listed just below it.
Delete
Delete the selected bind script command.
Execute Selected
Execute the command selected on the Bind Script Entries list.
Execute All
Execute all commands listed on the Bind Script Entries list.
Parent topic: Manage Packages and Plans
Related concepts
Manage Packages and Plans Tool
Related tasks
To execute one or all bind script lines
To create a bind script file
To open an existing bind script file
To edit an existing BIND command


Bind Packages tab

Collection Name
The name of the collection in which to store the package.
Library Name
The name of the library containing the source member from which you want to create the package. The <default> is DBRMLIB.
Member Name
The name of (program ID of) the source member from which you want to create the package.
Default Qualifier
The name of a schema to use as the default qualifier for this package. Optional.
Add
If the package does not already exist in the specified collection, add it to the collection.
Replace
If this package already exists in the collection, replace it; if it doesn't already exist, add it to the collection.
Replace Version
Replace the package version specified in the corresponding field with the generated package version.
Revert
Return all settings changed since opening the Packages tab to their original settings.
Execute
Execute the package to create it in the specified SQL Server database in preparation for binding into a plan. After binding, all versions of the bound package are automatically available to the plan.
Parent topic: Manage Packages and Plans
Related concepts
Package Specifications
Manage Packages and Plans Tool
Related tasks
To create a new package
To edit an existing BIND command


Bind Plans tab

Plan Name
The name of a plan that you can bind to your application.
Default Qualifier
The name of a schema to use as the default qualifier for this plan. Optional.
Packages
Bind existing packages into the plan.
DBRM Members
Bind source members into the plan.
DBRM Libraries
Bind source libraries into the plan in the order they appear on the Selected Libraries list, which represents the order in which HCOSS searches the libraries for DBRM members, using the first-found instance of a specified member.
Add
If the plan does not already exist in the SQL Server database, add it to the database.
Replace
Replace an existing plan of the same name with this plan.
Revert
Return all settings changed since opening the Plans tab to their original settings.
Name
A search string on which to refine the options on the list below. You can use the wild-card character % to represent any string or string fragment.
Search
Refine the options on the list below to those matching the search string in the corresponding Name field.
Available Collections
List of collections available in the current SQL database. Available in Packages mode only.
Available Packages
Packages included in the collection selected on the Available Collections list. Available in Packages mode only.
Selected Packages
Packages selected to add to or replace in the plan. Available in Packages mode only.
Available Members
List of DBRM members available for binding into the plan. Available in DBRM Members mode only.
Selected Members
Members selected to add to or replace in the plan. Available in DBRM Members mode only.
Available Libraries
List of DBRM libraries available for binding into the plan. Available in DBRM Libraries mode only.
Selected Libraries
Libraries selected to add to or replace in the plan. The order in which the libraries appear on this list determines the search order HCOSS uses to locate specified DBRM members. Available in DBRM Libraries mode only.
Add
Add the items selected on the list or lists to the left to the list on the right.
Remove
Remove the items selected on the list to the right.
Move Up
Reposition the library selected on the Selected Libraries list to appear before the libary listed just above it, changing the order in which the libraries are searched for DBRM members. Available in DBRM Libraries mode only.
Move Down
Reposition the library selected on the Selected Libraries list to appear after the libary listed just below it, changing the order in which the libraries are searched for DBRM members. Available in DBRM Libraries mode only.
Add to Script
Generate a script line representing the settings on this tab, and add it to the list of bind script entries found on the Bind Scripts tab.
Execute
Generate and execute a command representing the settings on this tab, thereby updating the SQL Server database, and generate a script line with a command representing the settings on this tab and add it to the list of bind script entries found on the Bind Scripts tab.
Parent topic: Manage Packages and Plans
Related concepts
Manage Packages and Plans Tool
Plan Specifications
Related tasks
To create a new plan
To edit an existing BIND command


Free Packages tab

Bound Packages
Lists all available bound packages.
Show package version information
Toggle the Version column in the Bound Packages grid.
Free Package(s)
Free all packages selected on the Bound Packages list.
Free All Packages
Free all packages on the Bound Packages list.
Parent topic: Manage Packages and Plans
Related concepts
Manage Packages and Plans Tool
Related tasks
To free one or more packages


Free Plans tab

Bound Plans
Lists all available bound plans.
Members
For the plan selected on the Bound Plans list, populates the Bound Members list with the DBRM members bound into the plan.
Packages
For the plan selected on the Bound Plans list, populates the Bound Packages list with the packages bound into the plan.
Bound Members
Shows the DBRM members bound into the selected plan. Available only when Members is selected.
Bound Packages
Shows the packages bound into the selected plan. Available only when Packages is selected.
Expand PKLIST to show package details
View all packages that resulted when binding the plan. Available only when Packages is selected.
Show package version information
Show the version for each package listed. Available only when Expand PKLIST to show package details is checked.
Free Plan
Free the plan selected on the Bound Plans list.
Free All Plans
Free all plans on the Bound Plans list.
Parent topic: Manage Packages and Plans
Related concepts
Manage Packages and Plans Tool
Related tasks
To free one plan or all plans


Results tab

Command Results
Shows the results of the bind execution.
Parent topic: Manage Packages and Plans
Related tasks
To execute one or all bind script lines


Data Mappings tab

DB2 Data Type
The DB2 database column type.
Encoding
The encoding associated with the corresponding DB2 data type, ASCII, EBCDIC, or UNICODE.
Data Storage Options
The method of data storage for the DB2 data type, For bit data, Mixed data, None, or SBCS data.
SQL Server Data Type
The SQL Server database column type to which HCOSS maps the corresponding DB2 Data Type.
Restore Defaults
Restores the default setting for each changed entry.
Parent topic: User Interface Reference


SQL Name tab

DB2 Function/Special Register
The name of a DB2 function or special register from the originating application.
SQL Server Equivalent
The SQL Server equivalent function or special register to which the corresponding DB2 function or special register is migrated.
Is Function
Identifies corresponding DB2 and SQL Server entries as functions.
Is Special Register
Identifies corresponding DB2 and SQL Server entries as special registers.
Restore Defaults
Restores the default setting for each changed entry.
Parent topic: User Interface Reference


Customize SQLCode Mappings

  • SQLCode Mappings tab
  • Deploy/Extract tab
Parent topic: User Interface Reference


SQLCode Mappings tab

SQL Server SQLCode
Lists SQL Server SQLCode settings.
Map to z/OS DB2 SQLCode
Lists DB2 SQLCode settings that map to the corresponding SQL Server SQLCodes.
Map to z/OS DB2 SQLState
Lists DB2 SQLState settings that map to the corresponding DB2 SQLCodes.
Save
Saves changes to the mfhcocds.txt file and saves original mappings to a backup file.
Restore
Loads previously defined mappings from a backup file.
Deploy/Extract
Takes you to the Deploy/Extract tab where you can deploy changes to your SQL Server database.
Parent topic: Customize SQLCode Mappings


Deploy/Extract tab

Data Source Name
The name of the SQL Server connection to the SQL Server database you want to update.
User ID
If required by your selected data source, type the user ID for your SQL Server login.
Password
If required by your selected data source, type the password for your SQL Server login.
Deploy to SS
Update the SQL Server database with changes made to the mfhcocds.txt file.
Extract from SS
Extract mapping information from the SQL Server database and saves it to a backup file.
Parent topic: Customize SQLCode Mappings


Options

Compare Data Options

Compare interval refresh time
Time interval in seconds to refresh the compare progress in terms of row count. Default is 2.
Maximum number of failures
Stops the compare when the specified number of failures (non-matching rows) is reached. Default is 50.

HCOSS Connections

Automatically Test Connections
True | HCOSS automatically tests your established database connections and automatically updates their status. Default.
False | You must update the status of each connection using the Refresh button in the Manage Connections tool.
Data source to use for testing DLL
The name of the SQL Server connection you want to set as the default testing database when generating DDL. If you do not provide a SQL Server connection, HCOSS does not perform any tests when generating DLL. (optional)
Name of current/default mainframe connection
The name of the mainframe connection you want to set as the default connection. (optional)
Name of the current/default target data source
The name of the SQL Server connection that you want to set as the default connection. (optional)
Timeout value for each connection
When checking a connection status, the number of seconds HCOSS waits for a returned status before moving on to check the next connection listed on the Connection List tab of the Manage Connections tool. Applies only to the Connection List tab. The default is 5.

HCOSS Directories

Local HCOSS Directory
The parent directory to the subdirectory structure used to store local generated HCOSS files. The default is %LOCALAPPDATA%\Micro Focus\Enterprise Developer\hcoss\genFileType.
Where genFileType is one of the following:
  • ApplicationAssessments
  • CompareTasks
  • DataTasks
  • DBRMDataSets
  • DDLTasks
  • Schemas
  • TargetLists
Shared HCOSS Directory
The parent directory to the subdirectory structure used to store shared generated HCOSS files. The default is %LOCALAPPDATA%\Micro Focus\Enterprise Developer\hcoss\genFileType.
Where genFileType is one of the following:
  • ApplicationAssessments
  • CompareTasks
  • DataTasks
  • DBRMDataSets
  • DDLTasks
  • Schemas
  • TargetLists
Note: All users must have READ/WRITE access to this directory.

HCOSS UAC Behavior

Prompt to automatically run as Administrator
True | When you start HCO for SQL Server as a standard user from the Start menu, and you are a member of the Administrators group, HCOSS prompts you to run HCOSS as an Administrator. Default.
False | HCOSS does not prompt you to run HCOSS as an administrator.
Run as Administrator if in Administrators Group
True | When you start HCO for SQL Server as a standard user from the Start menu, and you are a member of the Administrators group, HCOSS automatically runs in administrator mode. At startup, a Windows UAC prompt appears.
False | HCOSS does not automatically run HCOSS as an administrator, but prompts you to start as an administrator when you launch HCOSS from the Start menu as a standard user. Default.
Warn non-Administrator users of limited functionality
True | When running HCOSS as a standard user, HCOSS presents this prompt at startup to warn you that some functionality is limited when running in standard user mode. Default.
False | HCOSS presents a prompt at startup to warn you of limited functionality.

Log File Options

Automatically delete log files
Enable or disable the automatic deletion of log files older than the number of days specified by the Days before automatically deleting log files option. The default is False.
Days before automatically deleting log files
The number of days to wait before automatically deleting log files. Valid when Automatically delete log files is set to True. The default is 30.
Directory to write log files to
The parent directory to the subdirectory structure used to store HCOSS-generated log files. The default is %LOCALAPPDATA%\Micro Focus\Enterprise Developer\hcoss\genFileType.
Where logFileType is one of the following:
  • BindTasks
  • CompareTasks
  • Connections
  • DataTasks
  • DDLTasks
  • Schemas
  • TargetLists
Note: HCOSS does not create log files when Type of logging to do is set to Write log messages just to console, which is the default setting.
Type of logging to do
Set HCOSS to send log information to the console, a log file, or both. Default is Write log messages just to console.

Startup

HCOToolStartup
Specify the type of HCO for SQL Server startup environment, whether to start by loading information from the last session or to start with no previous information loaded. Default is Show empty environment.
Parent topic: User Interface Reference
Related concepts
HCOSS Toolset
Using HCOSS with Windows User Account Control (UAC)
Related tasks
To start HCO for SQL Server
To set HCOSS options


OpenESQL

  • ODBC Data Source Administrator
    Enables you to create an ODBC data source for database connection.
  • ADO.NET Connection Editor
    Use the ADO.NET Connection Editor to enable mixed-language applications to share connection strings.
Parent topic: Database Access


ODBC Data Source Administrator

Note: You must be logged into Windows as an administrator to create System DSNs.

You can use the ODBC Data Source Administrator to create a 32-bit or a 64-bit data source name (DSN) for connecting to a database:

  1. From your desktop, click Start > All Programs > Micro Focus Enterprise Server> Data Tools > Data Connections > ODBC Data Source Administrator > (32-bit) or (64-bit).
    Note: If using Windows 8 or later, press the Windows key on your keyboard and type ODBC Data; then select ODBC Data Sources (32-bit) or (64-bit).
  2. In the ODBC Data Source Administrator, click the User DSN or System DSN tab.
  3. Click Add.
  4. On the Name list, select a database type; then click Finish.

    This launches the Microsoft Create a New Data Source wizard.

  5. Complete the fields as appropriate; then click OK to close the ODBC Data Source Administrator.
Parent topic: OpenESQL


ADO.NET Connection Editor

The ADO.NET Connection Editor enables you to define and manage connection configurations used by the OpenESQL Managed Runtime when connecting a COBOL program to an ADO.NET or an ODBC data provider.

Connection information is stored in a standard .NET Framework repository, machine.config, which enables mixed language applications to share connection strings. The repository is accessible to all users of the machine on which it is installed.

The OpenESQL Managed Runtime supports any ADO.NET provider that supports the DbProviderFactory API.

Note:
  • We recommend that you use ADO.NET data providers when possible; however, the ADO.NET connection editor catalogues ODBC connections that you can use if necessary.
  • When you run the ADO.NET Connection Editor under operating systems that have User Access Control enabled, such as Windows 7, you must run it as an administrator if you are adding, deleting, or updating connections for System type connections. However, when updating User type connections, you do not need this elevated authority.
  • Connection Terminology
  • Cataloging an ADO.NET or ODBC Connection
  • Exporting and Importing Connections
  • Example Connection Settings
  • How to
  • Reference
Parent topic: OpenESQL


Connection Terminology

The following describes terminology used in this documentation with regard to database connections.

Connection

A set of specifications used to connect to a database. The specifications are dependent on the Data Provider.

Data Source
A specific set of connection specifications.
Data Source Name (DSN)
The name given to a specific set of connection specifications.
Data Provider
One of any .NET, ODBC, or OLE DB data providers.
Provider Data Source
The physical machine name or IP address where the data source is located. The Data Source field that appears on the Connection Settings list requires that you specify this provider data source rather than the DSN.
Catalog
A verb meaning to define a data source using a set of connection specifications, assign a name to the data source (DSN), and store the data source in the repository.
Parent topic: ADO.NET Connection Editor
Related tasks
To add a connection
To remove a connection


Cataloging an ADO.NET or ODBC Connection

OpenESQL Assistant automatically catalogs connections using ODBC and ODBC ADO.NET data providers if you have set your OpenESQL options to enable automatic cataloging. To use other ADO.NET data providers, you must catalog them manually using the ADO.NET Connection Editor. All available data providers are listed on the ADO.NET Connection Editor.

When you catalog a connection, the ADO.NET Connection Editor supplies default option specifications for the type of connection you catalog. You should edit the values to reflect the correct specifications for your data source. We provide templates for certain ADO.NET data providers as examples of what type of connection specifications are required and what their values should be. See the section Example Connection Settings for specific examples.

You also have the option of encrypting your connections in the repository. You might want to do this if your connection specifications include sensitive information such as a user ID and password used to access your application.

Parent topic: ADO.NET Connection Editor
Related concepts
Example Connection Settings
Related tasks
To add a connection
To remove a connection


Exporting and Importing Connections

You can copy your connections from one machine to another using the ADO Connection Editor's Export and Import functions. You do this by exporting connection information on one machine and importing it to another machine.

You can also import connection settings using the MFImportConn command.

Parent topic: ADO.NET Connection Editor
Related tasks
To import connections
To export connections
Related reference
MFImportConn command


Example Connection Settings

The following topics provide examples of appropriate connection settings for a SqlClient and a DB2 ADO.NET data provider.

  • SqlClient Data Provider
  • DB2 ADO.NET
Parent topic: ADO.NET Connection Editor
Related concepts
Cataloging an ADO.NET or ODBC Connection


SqlClient Data Provider

For a SqlClient data provider, you must provide values for the following connection settings:

Data Source
This is a Provider Data Source. The name of the SQL Server you want to use. If the server is local, you can usually specify localhost or (local).
Initial Catalog
The name of the database you want to access.
Integrated Security
Set this to True to use Windows security. It is set to False by default. When set to False, you must either provide values for the User ID and Password connection settings, or provide them in your program as part of the EXEC SQL CONNECT statement.
MultipleActiveResultSets
When using SQL Server 2005 or later, set this to True to allow multiple active result sets.
Parent topic: Example Connection Settings


DB2 ADO.NET

For a DB2 ADO.NET data provider, you must provide values for the following connection settings:

Database
The name of the database to access.
Server
The name of the database server. If the server is remote, you might also need to specify the TCP port number used by DB2, typically 50000. For example, servername:50000.
User ID and Password
You can specify these as connection settings or code them into your program using the EXEC SQL CONNECT statement.
Parent topic: Example Connection Settings


How to

  • To start the ADO.NET Connection Editor
  • To add a connection
  • To catalog an ODBC data provider
  • To remove a connection
  • To test a connection
  • To export connections
  • To import connections
Parent topic: ADO.NET Connection Editor


To start the ADO.NET Connection Editor

Do one of the following:

  • From your desktop, click Start > All Programs > Micro Focus Enterprise Server.
    Note: On Windows 8, Windows 10, and Windows Server 2012, you use the Start screen to invoke programs.
Important: To enable the adding, saving, importing, and deleting of System type connections, start the ADO.NET Connection Editor as an administrator.
Parent topic: How to
Related reference
ADO.NET Connection Editor - Main Window


To add a connection

  1. Start the ADO.NET Connection Editor.
  2. From the Settings Menu icon (Settings) menu, set each option as required to define the new connection. For a description of each option, see Settings menu.
  3. Click Add to start the Add an ADO.NET Connection wizard.
  4. Click Next.
  5. Type a data source name into the Data Source Name field; then click Next.
  6. Do one of the following to filter the list on the .NET Data Providers grid:
    • To view only the catalogued ADO.NET data providers, select Preferred Providers.
    • To view both the catalogued ADO.NET and ODBC data providers, select All Providers.
  7. Select the data provider that you want to use; then click Next.

    Depending on your provider selection, the wizard progresses to the Provider Connection Details, ODBC Data Providers, or OLE DB Data Providers page.

  8. For .NET providers, continue to the next step. For ODBD and OLE DB providers, do one of the following:
    • For ODBC providers, select an ODBC DSN on the ODBC DSNs list; then click Next.
    • For OLE DB providers, select an OLE DB provider from the list; then click Next.
  9. On the Provider Connection Details page, specify additional connection settings or modify default connection settings as required; then click Next.
    Note: Depending on the selected provider, this page shows all or some of the available connection settings including those required to connect. You can adjust all connection settings from the main window of the ADO.NET Connection Editor. See the context help located at the bottom of the main window for a description of each setting.
  10. Review your connection settings; then click Finish to create and catalog the connection.
  11. On the ADO.NET Connection Editor main window, adjust connection settings values as appropriate for your environment. Optional.
  12. Click Test to test your connection. Optional.
    Note: Alternatively, right-click the connection and select Test Connection from the context menu.
  13. Close the ADO.NET Connection Editor.
Parent topic: How to
Related concepts
Connection Terminology
Cataloging an ADO.NET or ODBC Connection
Related reference
Add an ADO.NET Connection wizard - start page
Name Your Connection page
.NET Data Providers page
OLE DB Data Providers page
ODBC System DSNs page
Provider Connection Details page


To catalog an ODBC data provider

  1. On a machine where the ADO.NET Connection Editor is installed and that has an ODBC connection already cataloged, start the ADO.NET Connection Editor as an administrator.
  2. Export the ODBC connection.
  3. On the machine where you want to add the ODBC connection, start the ADO.NET Connection Editor as an administrator.
  4. Import the exported ODBC connection information.
Parent topic: How to


To remove a connection

  1. Start the ADO.NET Connection Editor.
  2. If required to display the appropriate data source on the Data Source Names list, set the options on the Settings menu to match the settings for the data source you want to remove. For a description of each option, see Settings menu.
  3. On the Data Source Name list, select the connection you want to remove.
  4. Click Remove.
  5. Click OK.
  6. Close the ADO.NET Connection Editor.
Important: If you have the All framework/availability combinations setting checked when you remove a selected connection, all saved combinations are removed for the selected connection.
Parent topic: How to
Related concepts
Connection Terminology
Cataloging an ADO.NET or ODBC Connection
Related reference
ADO.NET Connection Editor - Main Window


To test a connection

  1. Start the ADO.NET Connection Editor.
  2. From the Settings menu, set the options as required to update the Data Source Names list to show the connection you want to test. For a description of each option, see Settings menu.
  3. On the Data Source Name list, click the connection you want to test.
  4. If your application requires a user ID and password to connect to a data source, type these into the User ID and Password fields on the Connection Settings list. Optional.
  5. Click Test. A message box appears reporting the status of the connection attempt.
    Note: Alternatively, right-click the connection and select Test Connection from the context menu.
  6. Click OK to clear the prompt.
Note:
  • When a connection test fails, a prompt appears showing an explanation of the failure, and prompts you to provide an alternative user ID and password and retry the connection; however, this is optional. To clear the prompt without providing a user ID or password, click Cancel.
  • If your application requires a user ID and password to connect to a provider data source, then for security reasons, do not save the user ID and password on the Connection Settings list. Information in those fields is used only to test the connection and is ignored when a CONNECT statement is executed. To provide your application with a user ID and password, pass the values as parameters in the CONNECT statement.
Parent topic: How to


To export connections

  1. Start the ADO.NET Connection Editor.
  2. To ensure that the connection(s) you want to export display on the Data Source Names list, set the options on the Settings Menu icon (Settings) menu as required. For a description of each option, see Settings menu.
  3. On the Data Source Names list, select the data sources you want to export, or check Select all connections. To select more than one connection, hold the Ctrl key down as you make your selections.
  4. Click Export Connections (Export) on the toolbar. This starts the Export ADO.NET Connections wizard.
  5. In the Export to field, type the full path to and filename of an XML file you want to contain exported information, or click Browse (Browse) to select a directory.
    Note:
    • If you choose to type in the full path and filename, you can name the file anything you want.
    • If you choose to browse to select a directory, the Connection Editor uses the default filename MFconnectInfo.xml. You can overtype the filename with a different name of your choice.
  6. Click Next.
  7. Review your export selections; then click Finish.
Parent topic: How to
Related concepts
Exporting and Importing Connections
Related reference
MFImportConn command


To import connections

  1. Start the ADO.NET Connection Editor.
  2. Click Import Connections (Import) on the toolbar. This starts the Import ADO.NET Connections wizard.
  3. In the Import from file field, type the full path to and filename of the XML file that contains exported connections, or click Browse Browse to select a file; then click Next.
  4. Select the connections you want to import, or check Select all connections. To select more than one connection, hold the Ctrl key down as you make your selections.
  5. Review the connections summary; then click Finish.
Note: You can also import connection settings using the MFImportConn command.
Parent topic: How to
Related concepts
Exporting and Importing Connections
Related reference
MFImportConn command


Reference

  • MFImportConn command
    Enables you to import connection settings previously exported from the ADO.NET Connection Editor.
Parent topic: ADO.NET Connection Editor


ADO.NET Connection Editor - Main Window

Import Connections wizard
Starts the Import ADO.NET Connections wizard.
Export Connections wizard
Starts the Export ADO.NET Connections wizard.
Provides access to the Settings menu.
Data Source Names
Lists the name of each data source whose definition matches the Type, Framework, and Availability options on the Settings menu.
Connection Settings
Connection specifications set by the data provider associated with the data source name selected on the Data Source Names list, plus the specifications you defined for the connection.
Add
Add a new data source.
Remove
Remove the selected data source from the repository.
Save
Save changes made to Connection Settings.
Test
Test the viability of the connection defined for the data source selected on the list of Data Source Names.
Settings ribbon
Located across the bottom of the window, shows the Availability, Framework, Save, and Encrypt settings set from the Settings menu.
Parent topic: Reference
Related tasks
To start the ADO.NET Connection Editor
To remove a connection


File Menu

Import
Launch the Import ADO Connections wizard, which enables you to import a connection that was previously defined and exported.
Export
Launch the Export ADO Connections wizard, which enables you to export a defined connection.
Exit
Close the ADO.NET Connections Editor.
Parent topic: Reference


Settings Menu icon Settings Menu

Save
All framework/availability combinations
When checked, upon saving a connection, the ADO.NET Connection Editor saves all applicable combinations of Framework and Availability settings for the connection. When unchecked, only the current Framework and Availability settings are saved.
Type
System
Select this to define connections in the system repository, and to show system data sources on the Data Source Names list.
Important: To add, edit, import, or remove a System connection, you must run the ADO.NET Connection Editor as an administrator.
User
Select this to define connections in the current user repository, and to show user data sources on the Data Source Names list.
Azure
Select this to define Azure SQL Database connections, and to show Azure data sources on the Data Source Names list.
Framework
2.0, 3.0, or 3.5
Select this to define connections for applications that use one of these .NET Framework versions, and to show existing connections that use these .NET Framework versions on the Data Source Names list.
4.0 or 4.5, 4.5, or 4.6
Select this to define connections for applications that use one of these .NET Framework versions, and to show existing connections that use these .NET Framework versions on the Data Source Names list. Default.
Availability
32-bit
Select this to define connections for applications built using x86, and to show existing 32-bit connections on the Data Source Names list. Default.
64-bit
Select this to define connections for applications built using x64 or built on a 64-bit operating system using ANYCPU, and to show existing 64-bit connections on the Data Source Names list.
Encrypt
Check this to encrypt your data source connection specifications in the repository. Default is unchecked.
Note: If you have also checked the All framework/availability combinations setting, all saved combinations are encrypted.
Parent topic: Reference


Add an ADO.NET Connection wizard - start page

The Add an ADO.NET Connection wizard enables you to define a new ADO.NET connection. As you work through the pages of this wizard, be prepared to provide a data source name, select a .NET data provider type, and select a specific data provider of your selected type.

  • Name Your Connection page
  • .NET Data Providers page
  • OLE DB Data Providers page
  • ODBC System DSNs page
  • Provider Connection Details page
Parent topic: Reference
Related tasks
To add a connection


Name Your Connection page

Data Source Name
The name of the new connection. This name appears on the Data Source Name list on the main window of the ADO.NET Connection Editor.
Parent topic: Add an ADO.NET Connection wizard - start page
Related tasks
To add a connection


.NET Data Providers page

.NET Data Providers
Lists the available .NET data providers and their supported versions.
Preferred Providers
Populates the .NET Data Providers grid with ADO.NET data providers only. Default.
All Providers
Populates the .NET Data Providers grid with both ADO.NET and ODBC data providers.
Parent topic: Add an ADO.NET Connection wizard - start page
Related tasks
To add a connection


OLE DB Data Providers page

OLE DB Data Providers
Lists the OLE DB data providers available for the .NET data provider type selected on the .NET Data Providers page of this wizard.
Parent topic: Add an ADO.NET Connection wizard - start page
Related tasks
To add a connection


ODBC System DSNs page

ODBC Data Sources
Lists the ODBC data sources defined for the current Availability and Type settings specified on the Settings menu.
Settings ribbon
Shows the bitness of the DSNs shown on the list.
Parent topic: Add an ADO.NET Connection wizard - start page
Related tasks
To add a connection


Provider Connection Details page

Connection Settings grid
Depending on the selected provider, lists all or some of the connection settings for the new connection, including those required to connect.
Note: All connection settings for each provider are listed on the main window of the ADO.NET Connection Editor where you can make additional adjustments if required.
Parent topic: Add an ADO.NET Connection wizard - start page
Related tasks
To add a connection


Export ADO.NET Connections - start page

The Export ADO.NET Connections wizard enables you to export the connection details for one or more defined data sources.

  • Select Connections to Export page
  • Specify an Export File page
Parent topic: Reference


Select Connections to Export page

Data Sources
Lists the names of ADO.NET data sources for which you can export connection details.
Select all connections
Check this to select all listed data sources for export of connection details.
Parent topic: Export ADO.NET Connections - start page


Specify an Export File page

Export to
The full path to and filename of an XML file to contain exported data source connection specifications.
Parent topic: Export ADO.NET Connections - start page


Import ADO.NET Connections - start page

The Import ADO.NET Connections wizard enables you to import one or more ADO.NET connections from an exported connections file.

  • Select a File to Import page
  • Select Connections to Import page
Parent topic: Reference


Select a File to Import page

Import from file
The full path to and filename of an XML file that contains exported data source connection specifications. Either type directly into the field or use the browse button.
Parent topic: Import ADO.NET Connections - start page


Select Connections to Import page

Data Sources
Lists the names of ADO.NET data sources contained in the export file.
Select all connections
Check this to select all listed data sources for import.
Parent topic: Import ADO.NET Connections - start page


MFImportConn command

Enables you to import connection settings previously exported from the ADO.NET Connection Editor.
Important: You must run this command from a 32-bit or a 64-bit Enterprise Developer command prompt, available from Start > All Programs > Micro Focus Enterprise Server > Tools.

The Start menu is not available on Windows 8, Windows 10, and Windows Server 2012. You use the Start screen to invoke programs.

Syntax

{MFImportConn32_v2 | MFImportConn32_v4 | MFImportConn64_v2 | MFImportConn64_v4} path:\exportedXMLfile {System | User} {32BIT | 64BIT}
Important: Use the executable that fits the type of connection you're importing to. In the executable file names, 32 represents 32-bit, 64 represents 64-bit, v2 represents .NET Framework versions 2.0, 3.0, or 3.5, and v4 represents .NET Framework 4.0.

Parameters

path | The full path to the XML file containing the exported connection settings
exportedXMLfile | The filename of the XML file containing the exported connection settings
System | Specify this to import the connection settings into the machine.config file for use by all users
User | Specify this to import the connection settings into the UserConnections32.config or UserConnections64.config file for use by the current user only
32BIT | Specify this for 32-bit connections
64BIT | Specify this for 64-bit connections
Parent topic: Reference
Related concepts
Exporting and Importing Connections
Related tasks
To import connections
To export connections


MBDT Configuration Utility

Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability; however, this feature is not intended for production use and it is not supported as such. Furthermore, Micro Focus does not guarantee that this feature will be delivered at a GA level and if it is, then the functionality provided might differ considerably from this technology preview.

The MDBT Configuration Utility enables you to set default dialect and commit behavior options.

You can run the MBDT Configuration Utility from the Start menu, or from the command line.

  • How to
  • mbdtconfig command
    Runs the command-line version of the MBDT Configuration Utility.
Parent topic: Data Access
Related tasks
To start the MBDT Configuration Utility
Related reference
mbdtconfig command


How to

Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability; however, this feature is not intended for production use and it is not supported as such. Furthermore, Micro Focus does not guarantee that this feature will be delivered at a GA level and if it is, then the functionality provided might differ considerably from this technology preview.
  • To start the MBDT Configuration Utility
  • To set a default dialect for SQLTP2xx
  • To set a default commit behavior for SQLUTBxx
Parent topic: MBDT Configuration Utility


To start the MBDT Configuration Utility

Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability; however, this feature is not intended for production use and it is not supported as such. Furthermore, Micro Focus does not guarantee that this feature will be delivered at a GA level and if it is, then the functionality provided might differ considerably from this technology preview.
From the Start menu:
  • Click Start > All Programs > Micro Focus Enterprise Server > Configuration > MBDT Configuration Utility.
    Note: The Start menu is not available on Windows 8, Windows 10, and Windows Server 2012. You use the Start screen to invoke programs.
From the command line:
  • Open an Enterprise Server command prompt; then issue the mbdtconfig command. See mbdtconfig command for details.
Parent topic: How to
Related concepts
MBDT Configuration Utility
Related tasks
To set a default dialect for SQLTP2xx
To set a default commit behavior for SQLUTBxx
Related reference
mbdtconfig command


To set a default dialect for SQLTP2xx

Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability; however, this feature is not intended for production use and it is not supported as such. Furthermore, Micro Focus does not guarantee that this feature will be delivered at a GA level and if it is, then the functionality provided might differ considerably from this technology preview.
  1. Start the MBDT Configuration Utility.
  2. In the Database Selection group, select either HCOSS or Agnostic.
  3. Close the MBDT Configuration Utility.
Parent topic: How to
Related tasks
To set a default commit behavior for SQLUTBxx
To start the MBDT Configuration Utility


To set a default commit behavior for SQLUTBxx

Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability; however, this feature is not intended for production use and it is not supported as such. Furthermore, Micro Focus does not guarantee that this feature will be delivered at a GA level and if it is, then the functionality provided might differ considerably from this technology preview.
  1. Start the MBDT Configuration Utility.
  2. In the Commit group, select either Single commit... or Multiple commit....
  3. If you have selected Multiple commit..., in the Batch Size field, type the number of rows to process in each batch before committing.
  4. Close the MBDT Configuration Utility.
Parent topic: How to
Related tasks
To set a default dialect for SQLTP2xx
To start the MBDT Configuration Utility


mbdtconfig command

Runs the command-line version of the MBDT Configuration Utility.
Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability; however, this feature is not intended for production use and it is not supported as such. Furthermore, Micro Focus does not guarantee that this feature will be delivered at a GA level and if it is, then the functionality provided might differ considerably from this technology preview.
Important: You must run this command from a 32-bit or a 64-bit Enterprise Server command prompt, available from Start > All Programs > Micro Focus Enterprise Server > Tools.

On Windows 8, Windows 10, and Windows Server 2012, you use the Start screen to invoke programs.

Syntax

mbdtconfig -t {H[COSS] | A[gnostic]} | -s size={0 | n}}

Parameters

-t
Sets the database type.
H[COSS]
Indicates a SQL Server database in which CREATE SCHEMA object statements are z/OS DB2 statements.
A[gnostic]
Indicates a SQL Server, DB2 LUW, or Oracle database in which CREATE SCHEMA object statements are specific to the DBMS vendor specifications. This option does not support mainframe DB2 DDL. Default.
-s
Sets the commit behavior.
size=
Set this to zero (0) to issue a single commit after all records have been loaded. Default.

Provide a number, represented here as n, to indicate multiple commits, each after n rows have been processed.

Parent topic: MBDT Configuration Utility
Related concepts
MBDT Configuration Utility
Related tasks
To start the MBDT Configuration Utility


Data Files

  • Data File Tools
  • 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: Data Access


Data File Tools

Note: This is a technology preview feature. It is being made available to allow you to edit test data and provide feedback on this new capability; however, this feature is not intended for the editing of production data and its use is not supported as such.

Micro Focus Data File Tools is a standalone text editor in which to create and edit data files for use in your COBOL testing environment. The files you create can belong to a Fileshare server or reside locally on your machine. You can also open existing data sets within your Enterprise Server regions, for editing.

Data File Tools comprises two editors, producing two different types of file. Use the files produced by the two editors, within the Data File Editor, to produce a rich data editing experience.

Data File Editor
The Data File Editor is a tabbed pane within the Data File Tools window in which to create, view, and edit data files of different organizations. This editor also provides a comprehensive filtering tool, enabling you to filter on only the records you require.
Structure File Editor

The Structure File Editor is a tabbed pane within the Data File Tools window in which to create and edit the contents of structure files. Structure files are applied to data files so that the data files are easier to view and edit.

Data File Tools is a multi-tabbed environment in which you can have one or more data files and structure files open (within their respective editors) at the same time. Switching between tabs enables you to edit files simultaneously.

  • Current Restrictions
  • Accessing Data File Tools
  • Preferences
  • Using the Data File Editor
  • Using the Structure File Editor
Parent topic: Data Files


Current Restrictions

Note: This is a technology preview feature. It is being made available to allow you to edit test data and provide feedback on this new capability; however, this feature is not intended for the editing of production data and its use is not supported as such.
This version of Data File Tools has the following restrictions:
  • This version of Data File Tools should only be used with the version of Visual COBOL or Enterprise Developer that it was installed with. The executable is not compatible with previous versions of either of these development products.
  • Editing files is not supported if your environment contains any form of filename manipulation; for example, the DATAFILE and FILESUFFIX options within an extfh.cfg file, or the setting of the COBDATA environment variable. To work around this restriction, open Data File Tools from the Windows menu, ensuring no such filename manipulation variables are set at a system level.
  • You cannot create new structure files from a 64-bit command prompt.
  • The only supported UNIX platforms are SUSE and Red Hat.
  • There is no support for Unicode files.
  • There is no file conversion functionality.
  • There is no support for old structure (.str) files and profile files (.pro files), produced in Classic Data File Tools. This version uses a .dfs structure file to contain the information previously held in the other two file formats.
  • All files are opened in Data File Tools using a lock mode of EXCLUSIVE.
  • The following fields are supported but are not validated; they are always shown as valid:
    • Fields of the following type:
      • PIC *
      • PIC $
      • PIC 1
      • PIC B
      • PIC G
      • PIC N
      • PIC Z
      • Usage COMP-1
      • Usage COMP-2
      • Usage COMP-6
    • Numeric items containing:
      • exponents
      • the following separators: [v], [/], [,], [.], [0]
      • the following sign control symbols: [+] , [-], [CR], [DB]
    • The following modifiers:
      • BLANK WHEN ZERO
      • RENAMES
      • SYNC
  • There is no support for the following types of data file:
    • ACUCOBOL-GT (Vision)
    • IMS
    • PL/I
    • RM/COBOL
  • When editing files that have record layouts applied, take care that you enter the correct type of data. Invalid data will be formatted to match the data type of the field.
  • When creating a structure file, .idy files must be compiled with at least version 2.3 of the development product.
  • The editor is unable to display the Euro character (€) correctly. If you open a file that contains the character, it will be preserved after the file is closed as long as you do not edit it directly.
  • Line sequential files cannot contain binary characters. The INSERTNULL configuration option, which is ON by default, is ignored.
  • Line sequential file and relative files both use 0D0A as a record terminator on Windows, and 0A as a record terminator on UNIX. The LSRECDELIM and RELRECDELIM configuration options are ignored.

  • You cannot insert or append records for sequential ESDS files.

    Note: The normal file system only allows you to append records to the end of this type of file.

  • You cannot delete or resize records for ESDS files.

    Note: The normal file system does not allow you to delete or resize records for this type of file either.
  • When using compressed files through Fileshare, user-defined compression routine executables must reside on both the client and the server machine (and be on the PATH) in order to effectively edit the data file.
Parent topic: Data File Tools


Accessing Data File Tools

Note: This is a technology preview feature. It is being made available to allow you to edit test data and provide feedback on this new capability; however, this feature is not intended for the editing of production data and its use is not supported as such.
The following sections describe how you can access Data File Tools.
  • Launching Data File Tools from a Command Line Prompt
  • Launching Data File Tools from the Start Menu
Parent topic: Data File Tools


Launching Data File Tools from a Command Line Prompt

Use the following syntax to launch the Data File Tools IDE from your product-name command line prompt:

mfdatatools2 [file-type][path][filename][option...]
file-type
This parameter is optional. If omitted, Data File Tools opens without a file loaded. If specified, file-type must be one of:
/data
Specifies that the file to be opened is a data file, and will be opened in the Data File Editor.
/dfs
Specifies that the file to be opened is a structure file, and will be opened in the Structure File Editor.
/create_dfs
Specifies that a structure file is to be created for the specified data file, by either specifying the data file or an associated .idy file.
path
This parameter is optional. If specified, Data File Tools attempts to open the named file located in the path specified. If omitted, Data File Tools attempts to open the named file located in the current working directory.
filename
This parameter is optional. If specified, Data File Tools uses the path (if specified) and filename to open the file in the appropriate editor. If omitted, Data File Tools opens with no file loaded.
option
These parameters are optional, and will only take effect if the /data file type is also specified. If omitted, Data File Tools opens at the Open File dialog box, where you can set the required options. You can specify one or more of:
/org org-type
The organization of the file. org-type can be one of:
seq
Sequential files.
lseq
Line sequential files.
rel
Relative files.
idx
Indexed files.
/reclen
The maximum record length.
Parent topic: Accessing Data File Tools
Related information
Launching Data File Tools from the Start Menu


Launching Data File Tools from the Start Menu

On Windows platforms, launch Data File Tools from the Start menu:

  • Click Start > All Programs > product-name > Data Tools > Data File Tools.
Parent topic: Accessing Data File Tools
Related information
Launching Data File Tools from a Command Line Prompt


Preferences

Note: This is a technology preview feature. It is being made available to allow you to edit test data and provide feedback on this new capability; however, this feature is not intended for the editing of production data and its use is not supported as such.

You can set the following preferences when using the Data File Editor:

Records per page
Set the amount of records you want to display per page. The more records you display per page, the more memory that is required; therefore, reduce the amount of records per page if you receive memory problems. Use the [image] and [image] icons to navigate the pages of records.
Note: You must restart Data File Tools before any changes to this setting take effect.
Temporary Directory
Set the location of a temporary directory that is required in order to filter a data file. You can specify either an absolute or a relative (to the current working directory) path. An invalid path, or no path at all, will produce an error when you attempt to apply a filter.
Padding Character
Each new record is immediately padded with the characters you specify here for both ANSI and EBCDIC encoding. Enter the character in the top cell of the box next to the encoding name.
  • Set the Editor Preferences
Parent topic: Data File Tools


Set the Editor Preferences

  1. From the Data File Tools window, click Tools > Preferences, or click [image] (Preferences).

    The Preferences dialog box appears.

  2. To set the amount of records per page, in the Miscellaneous section, enter the number of records in the Records per page field. The maximum number of records you can have per page is 10,000.
    Note: You must restart Data File Tools before any changes to this setting take effect.
  3. To set the temporary directory, which is required to apply a filter to a data file, either type a valid path, or click Browse and select one.
    Note: You can enter a relative path, which will be relative to the current working directory.
  4. To specify the padding character, in the top cell of the box next to the required encoding name, enter the character: its hexadecimal equivalent is displayed beneath.
  5. Click OK.

    The dialog box is closed.

Parent topic: Preferences


Using the Data File Editor

Note: This is a technology preview feature. It is being made available to allow you to edit test data and provide feedback on this new capability; however, this feature is not intended for the editing of production data and its use is not supported as such.

The Data File Editor is the editor in which to create, view, and edit data files of different organizations. This editor also provides comprehensive tools that enable you to filter on the records you require.

The Data File Editor is a multi-tabbed environment in which you can have one or more data files open at the same time, each in their own separate tab. Switching between tabs enables you to edit files simultaneously.

Each open file has a lock mode of EXCLUSIVE applied to it, and so will be locked from other users until the file is closed in the Data File Editor.

  • Creating Data Files
    Create data files of different organizations, then use the Data File Editor to add records to the file.
  • Editing Data Files
    There are a number of ways in which you can edit the records within formatted and unformatted data files. The types of edits available are sometimes dependent on the type of organization of the file.
  • Viewing and Filtering Data Files
    Often, large data files can be difficult to scan or information within it can be difficult to locate. Data File Tools provides a number of tools to help display or locate information within formatted and unformatted data files.
  • Backing Up Data Files
    Before you edit a data file, you can back up the current version when you open the file.
Parent topic: Data File Tools


Creating Data Files

You can create new data files for all supported file organizations.

When creating a new file, specify the details that make up the file header, such as the file organization and record length details, because the Data File Editor needs these details to open the file correctly each time, for editing.

On creation of the file, these details can be written into the file header for files that do contain a header; such files are indexed files, (record) sequential, and relative files that contains variable record lengths. For file organizations that do not contain a file header, you can save these details to a structure file (.dfs file), by checking the Save details check box on the Create New File dialog box.

For indexed files, you can also define the required indexed keys.

  • Create a Non-indexed Data File
  • Create an Indexed Data File
Parent topic: Using the Data File Editor


Create a Non-indexed Data File

Use this procedure to create a (record) sequential, line sequential, or relative data file. To create an indexed data file, see Create an Indexed Data File.

  1. From the Data File Tools window, select File > New, or click [image] (New File).

    The New dialog box appears.

  2. Select Data File, then click OK.

    The Create New File dialog box appears.

  3. In the Filename field, type the name of the data file.
    Tip: You can specify:
    • An absolute path: for example, c:\path\to\file\dat-name.dat.
    • A relative path: for example, dat-name.dat. (The .dat file is created in the directory in which Data File Tools was started.)
    • A Fileshare path: for example, $$FS-server-name\dat-name.dat.
  4. If you are applying a structure file to the new data file, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select a structure (.dfs) file.

    If you do apply a structure file, the details within it are used to populate the File Details section.

  5. If you have not applied a structure file, in the File Details section, click [image] beside Organization, then select the organization for the file.
  6. If the records will be of variable length, check Variable length records.
  7. Specify the Min Length (only applicable for variable length records), and Max Length values.
  8. Check Save details to save the file details.

    If selected, a new filename.dfs file is created. In future, specify this file when opening the data file, so that the file details are retained.

    Note: For certain file types, Save details is not available, because the details are stored in the file header of the data file instead.
  9. Click Create File.

    The file is created, then opened in the editor.

Parent topic: Creating Data Files
Related information
Create an Indexed Data File


Create an Indexed Data File

Use this procedure to create an indexed data file. To create a (record) sequential, line sequential, or relative data file, see Create a Non-indexed Data File.

  1. From the Data File Tools window, select File > New, or click [image] (New File).

    The New dialog box appears.

  2. Select Data File, then click OK.

    The Create New File dialog box appears.

  3. In the Filename field, type the name of the data file.
    Tip: You can specify:
    • An absolute path: for example, c:\path\to\file\dat-name.dat.
    • A relative path: for example, dat-name.dat. (The .dat file is created in the directory in which Data File Tools was started.)
    • A Fileshare path: for example, $$FS-server-name\dat-name.dat.
  4. If you are applying a structure file to the data file, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select a structure (.dfs) file.

    If you do apply a structure file, the details within it are used to populate the File Details section.

  5. If you have not applied a structure file, in the File Details section, click [image] beside Organization, then select Indexed.
  6. Click [image] beside File Format, then select an indexed file format.

    For an indexed file, you must specify a primary key, and may specify one or more alternate keys.

  7. Click Define Keys.

    The Key Information dialog box appears.

  8. Add a primary key:
    1. In the Key section, click Add.

      A primary key is created, with a default component. A component defines the start position and length of the key within each record.

    2. In the Key compression section, select the appropriate check boxes:
      Leading spaces
      Removes the leading spaces within the value of the key.
      Trailing spaces
      Removes the trailing spaces within the value of the key.
      Duplicates
      For alternate keys only. Only the first duplicate key is contained in the file; subsequent duplicate values are not stored, but information is stored to enable correct recreation of the keys.
    3. Click the Component tab. Details for the default component, created when the key was added, appears.
    4. In the Key Component section, specify the Offset and Length values of the primary key.

      For example, if the key is going to be the first 3 bytes of the record, specify Offset:0, Length:3.

    5. To create a split key, click Add and repeat the last step to create one or more additional components to the key.
      Tip: To delete a component, select it, then click Delete.
    6. Click OK.

      The primary key is created.

  9. If required, add an alternate key:
    1. Click Define Keys.
    2. In the Key section, click Add.

      An Alt Key <number> key is created, with a default component.

    3. In the Key Options section, select the appropriate check boxes:
      Allow duplicates
      Allows duplicate values for this key.
      Sparse
      Allows you to define an ANSI or EBCDIC value that when used as the value of this key, will not be stored in the index file; thus saving space.
    4. In the Key compression section, select the appropriate check boxes:
      Leading spaces
      Removes the leading spaces within the value of the key.
      Trailing spaces
      Removes the trailing spaces within the value of the key.
      Duplicates
      For alternate keys only. Only the first duplicate key is contained in the file; subsequent duplicate values are not stored, but information is stored to enable correct recreation of the keys.
    5. Click the Component tab.

      Details for the default component, created when the key was added, appear.

    6. In the Key Component section, specify the Offset and Length values of the alternate key.

      For example, if the key is going to be the next 3 bytes of the record after the primary key, specify Offset:3, Length:3.

    7. To create a split key, click Add and repeat the last step to create one or more additional components.
      Tip: To delete a component, select it, then click Delete.
    8. Click OK. The alternate key is created.
  10. If the records will be of variable length, select Variable length records.
  11. Specify the Min Length (only applicable for variable length records), and Max Length values. All the details you specify in the File Details section are written to the file header of the indexed file.
  12. Click Create File.

    The file is created, then opened in the editor.

Parent topic: Creating Data Files
Related information
Create a Non-indexed Data File


Editing Data Files

There are a number of ways in which you can edit the records within formatted and unformatted data files. The types of edits available are sometimes dependent on the type of organization of the file.

A formatted data file is one that has a structure file applied to it, and therefore is being displayed using one or more record layouts. An unformatted data file does not have a structure file applied, and therefore displays its records unformatted, as one continuous string, per record.

  • Editing Data Sets in Enterprise Server
  • Insert a Record
  • Edit an Unformatted Record
  • Edit a Formatted Record
  • Layout and Field Validation
  • Edit a Record Using Hexadecimal Values
  • Delete a record
Parent topic: Using the Data File Editor


Editing Data Sets in Enterprise Server

You can access and edit existing data sets within an Enterprise Server region using Data File Tools. The procedure to open a data set in the Data File Editor is different from opening a data file, but once opened in the editor, edit it in the same way as you would a data file.

Data sets opened in this way use the ENQ and DEQ locking mechanisms. You are also required to authenticate your request to open a data set if you are connecting to a region that has an external security manager enabled.

Data sets will usually be opened through a Fileshare server running in the region that you connect to. Although, this does not have to be the case if you are opening data sets on a local region, as you can bypass Fileshare and open them directly, which can give faster access. In fact, in this scenario Fileshare does not even need to be configured.

If you are attempting to open data sets on a remote Enterprise Server region, a Fileshare server that is configured for TCP/IP needs to be running on that server, and you must set the CCITCP2 environment variable on your machine to the IP address of the remote Enterprise Server before you open Data File Tools.
Note: The remote Fileshare server does not need to be configured for the region and data sets you intend to edit; it just needs to be running at the time you connect to the remote Enterprise Server.

To use a structure file with a data set, the structure file must be stored locally, which means that, unlike when opening local data files, Data File Tools cannot auto-select a structure file of the same name and same location if you are connecting to a remote machine; you must select one each time you open the data set.

Note: This functionality does not support the iFileshare configuration of an Enterprise Server region.
  • Opening a Data Set in Enterprise Server
Parent topic: Editing Data Files
Related information
Insert a Record
Edit an Unformatted Record
Edit a Formatted Record
Layout and Field Validation
Edit a Record Using Hexadecimal Values
Delete a record


Opening a Data Set in Enterprise Server

Before you start, you must ensure that the Enterprise Server region is running; additionally, if you are connecting to a remote Enterprise Server, you must set the CCITCP2 environment variable in your environment to the IP address of the Enterprise Server with which you are going to connect, and a Fileshare server must be running within the region.
  1. In the Data File Tools window, select File > Open via ES. The Open File via Enterprise Server dialog box appears.
  2. In the ES Region section, for the region that contains the data set, type the IP address in the Host field, and the port number in the ESMAC Port field.
    Note: If the Enterprise Server is on your local machine, type localhost in the Host field. To locate the ESMAC port number, view the Web Services and J2EE listener details: the port number is displayed after the IP address and colon.
  3. In the Authentication section, if the region has an external security manager enabled, type the ID and group for a user that has access to the data set you intend to edit.
    Note: If the region does not have an external security manager enabled, do not enter any details in these fields.
  4. Click Connect.

    You connect to the Enterprise Server region specified, and the data sets that you have permission to update appear. If you are using authentication details, and they are either incorrect or do not grant access to any data sets, a message appears.

  5. Highlight the required data set.
  6. If you are opening a data set on a remote Enterprise Server, in the Fileshare Server section, check Use Fileshare, then type the name of a Fileshare server running on the remote Enterprise Server.
  7. Click OK.

    The Open Data File dialog box appears.

  8. Complete the Open Data File dialog box as you would for any other data file, then use the Data File editor, again, as you would for any other data file.
    Note: Structure files must be stored locally; therefore, if you open a remote data set, you must select any required structure file for it each time the data set is opened.
Parent topic: Editing Data Sets in Enterprise Server


Insert a Record

Note: A new record is immediately padded to its maximum length with the character you specify in the Preferences section.
  1. In the Data File Tools window, ensure you have a data file open.
  2. Right-click the required record, then select Insert Record Before or Insert Record After, as appropriate.
    Note: If the file currently has no records or is an indexed file, select Insert Record.

    If you are inserting a record into a data file that is using a structure file, the Select a Record Layout dialog box appears.

  3. Click [image] and select the required layout to use to complete the record details.
    Note: This does not necessarily have to be the record layout that the record will use once part of the data file.

    The green bar indicates where the record will be inserted.

    The editor switches to Insert mode, as indicated in the status bar.

  4. If the data file is unformatted (that is, not using a record layout), type the new record text in the free-text editing field in the bottom pane, then press Enter; the padding characters are overwritten as you type.

    For files with variable record lengths that are not using a layout, the length of any new record is set to the file's maximum record length by default. You can change the length of the record (within the minimum and maximum boundaries) by using [image] (Edit Record Length); any new record length is set for the current record only.

  5. If the data file is formatted, type the new record text in the layout fields, pressing Enter to move to the next field.
  6. Click [image] (Save Record) to save the record. The new record is inserted.
Parent topic: Editing Data Files
Related concepts
Create an Indexed Data File
Create a Non-indexed Data File
Related reference
Preferences
Related information
Editing Data Sets in Enterprise Server
Edit an Unformatted Record
Edit a Formatted Record
Layout and Field Validation
Edit a Record Using Hexadecimal Values
Delete a record


Edit an Unformatted Record

An unformatted record is a record that belongs to a data file that does not have a structure file applied to it, and therefore is not using a layout.
  1. In the Data File Tools window, ensure you have an unformatted data file open.
  2. Select the required record to edit, then click [image] (Edit Record).

    The record text in the bottom pane becomes editable.

  3. Edit the text in the bottom pane, then click [image] (Save Record).
    Tip: When editing records and fields, you can edit in Overwrite or Insert mode, which works much the same as it does on any conventional word processing package. Click Ins to toggle between the modes; the current mode (INS or OVR) is displayed in the status bar at the bottom of the screen.

    The record is updated, and the data file is saved automatically.

Parent topic: Editing Data Files
Related information
Editing Data Sets in Enterprise Server
Insert a Record
Edit a Formatted Record
Layout and Field Validation
Edit a Record Using Hexadecimal Values
Delete a record


Edit a Formatted Record

A formatted record is a record that belongs to a data file that has a structure file applied to it, and therefore is being displayed using a layout. The level numbers that are displayed correspond to the level numbers from the .idy file used when creating the structure file.
Note: When editing files that have record layouts applied, take care that you enter the correct type of data. Invalid data will be formatted to match the data type of the field.
  1. In the Data File Tools window, ensure you have a formatted data file open.
  2. In the left-hand pane, select the required record to edit.
  3. In the right-hand pane, double-click the field value that you want to edit.

    The field becomes editable.

  4. Edit the text in the field, then click [image] (Save Record).
    Tip: When editing records and fields, you can edit in Overwrite or Insert mode, which works much the same as it does on any conventional word processing package. Click Ins to toggle between the modes; the current mode (INS or OVR) is displayed in the status bar at the bottom of the screen.

    The record is updated, and the data file is saved automatically.

Parent topic: Editing Data Files
Related information
Editing Data Sets in Enterprise Server
Insert a Record
Edit an Unformatted Record
Layout and Field Validation
Edit a Record Using Hexadecimal Values
Delete a record


Layout and Field Validation

When using a record layout, the following validation occurs:

  • The data in each field is validated to ensure is it compatible with the field's PICTURE string, which is determined by the structure file. The validation uses the same logic as is used in your COBOL system; for example, a character in a COMP 9 USAGE DISPLAY field is invalid.
  • The size of the record layout is validated to ensure that it is within the bounds of any minimum or maximum record length specified for the data file.

If any field within a record is invalid or the size of the layout is outside the bounds of minimum or maximum record length, the whole record is marked as invalid, as indicated by [image] displayed beside the name of the layout in use. In the case of an invalid field, [image] is displayed in the field. Selecting an invalid field enables you to reinitialize its content to a valid value (such as zeroes for a numeric field). If you do not re-initialize, you can manually edit the existing value, or leave the field value as invalid.

If all the fields within a record are valid, [image] is displayed beside the name of the layout.

You can filter on invalid (and valid) records using the normal filtering process, by specifying the Is Invalid (and Is Valid) operator(s).

Parent topic: Editing Data Files
Related information
Editing Data Sets in Enterprise Server
Insert a Record
Edit an Unformatted Record
Edit a Formatted Record
Edit a Record Using Hexadecimal Values
Delete a record


Edit a Record Using Hexadecimal Values

You can directly edit hexadecimal values within a data file.

Note: When editing files that have record layouts applied, take care that you enter the correct type of data. Invalid data will be formatted to match the data type of the field.
  1. In the Data File Tools window, ensure you have Hex View enabled; see Show Contents of a Data File in Hexadecimal.
  2. In the Hex pane, select the first character in the hex pair.

    This highlights the hex pair and its corresponding character in the Unformatted Record pane and the field pane beneath the layout.

  3. Type a new two-digit/character hex pair, then press Enter.

    The ANSI/EBCDIC character is updated.

    Note: You cannot enter a numerical or character value if it results in an invalid hex pair.
Parent topic: Editing Data Files
Related information
Editing Data Sets in Enterprise Server
Insert a Record
Edit an Unformatted Record
Edit a Formatted Record
Layout and Field Validation
Delete a record
Show the Contents of a Data File in Hexadecimal


Delete a record

  1. In the Data File Tools window, ensure you have the required data file open.
  2. Right-click the required record, then click Delete Record.
  3. Click Yes to confirm.

    The record is deleted, and the data file is saved automatically.

Parent topic: Editing Data Files
Related information
Editing Data Sets in Enterprise Server
Insert a Record
Edit an Unformatted Record
Edit a Formatted Record
Layout and Field Validation
Edit a Record Using Hexadecimal Values


Viewing and Filtering Data Files

Often, large data files can be difficult to scan or information within it can be difficult to locate. Data File Tools provides a number of tools to help display or locate information within formatted and unformatted data files.

One of the main navigational aids is to apply a structure file to the data file, which provides one or more layouts in which to present each record in a much more user friendly way; see Creating Structure Files and Layouts for more information.

There are also navigational arrows (or you can use the cursor keys) to move from one record to the next. You can also jump directly to a record by entering the record number in the Record Number box.

For larger data files, an easier solution is to filter the file on specific information. The filter allows you to use multiple criteria in order to filter the records that are displayed. After the filter has been applied, you can switch between the entire file and the filtered results using the Records option.

  • View File Information
  • Filtering a Data File
  • Navigate a Data File
  • Show the Contents of a Data File in Hexadecimal
  • Select the Encoding for a Data File
  • Order a Data File using Indexed Keys
Parent topic: Using the Data File Editor
Related reference
Creating Structure Files and Layouts


View File Information

  1. From the Data File Tools window, click File > Open, or click [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required data file, then click Open.

    The Open Data File dialog box appears.

  3. If you are applying a layout, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select a structure (.dfs) file.
  4. Click Open File.

    The file is displayed on its own tab in the main window.

  5. In the File group, click [image] (File Information).

    Basic file information for the selected file appears.

  6. Click OK to close the dialog box.
Parent topic: Viewing and Filtering Data Files
Related information
Filtering a Data File
Navigate a Data File
Show the Contents of a Data File in Hexadecimal
Select the Encoding for a Data File
Order a Data File using Indexed Keys


Filtering a Data File

Applying a filter to the current data file enables you to limit the amount of records that are displayed at a time.

Your filter is defined by one or more conditions, and you can produce filtered results that include records matching all or any one of those conditions.

There are two types of condition that you can use:

Reference condition
A reference condition uses the same principles as reference modification in your COBOL syntax. You specify the starting position within a record in which to start filtering, and then specify the number of positions on from that in which to filter; for example, values of 7:3 will filter on ositions 7 to 9 within each record, as indicated below

Field condition
This type of condition is only available if you have applied a layout to your data file. A field condition filters the entire contents of the selected field. You can select any non-group field in the layout on which to filter.

For both types of condition, you select a value that you wish to filter and an operator (for example, greater than, contains, or not equal to). There are also supplementary criteria to add to the condition, such as making it case sensitive, or trimming leading or trailing space from the area filtered.

Data File Tools retains the last set of filtered results until another filter is applied, which enables you to toggle between displaying these results and displaying the original data file.

  • Filter the Data File
  • Filter Operators
Parent topic: Viewing and Filtering Data Files
Related information
View File Information
Navigate a Data File
Show the Contents of a Data File in Hexadecimal
Select the Encoding for a Data File
Order a Data File using Indexed Keys


Filter the Data File

The results of a filter include each record that contains data that satisfied the conditions.

  1. From the Data File Tools window, click File > Open, or click [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required data file, then click Open.

    The Open Data File dialog box appears.

  3. If you are applying a layout, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select a structure (.dfs) file.
  4. Click Open File.

    The file is displayed on its own tab in the main window.

  5. In the Navigation group, click [image] (Filter).

    The Filter dialog box appears.

    Note: If a message appears warning you that a valid temporary directory does not exist, on the Tools menu, click Preferences, enter a valid directory in the Temporary Directory field, then repeat the last step.

    Filters are constructed by adding one or more conditions.

  6. To add a reference condition:
    1. Click New Ref.

      The basic filter elements appear.

    2. In the Field field, enter the start position and the number of positions on from that in which to filter on within each record; for example, values of 7:3 will filter on positions 7 to 9 within each record, as indicated below:

    3. In the Alphanumeric field, click [image] and select the type of text to filter: Text or Numeric.
    4. In the Operator field, click [image] and select the required operator.
    5. In the Value field, enter the filter value.
    6. (Optional) Select Trim to remove any leading or trailing spaces, or leading zeroes from each record before it is filtered.
    7. (Optional) Select Case to ensure the filtered content is case sensitive.
  7. To add a field condition:
    Note: This type of condition is only available if you are using a layout.
    1. Click New Field.

      The basic filter elements appear.

    2. In the Field field, click [image] and select the field on which to filter.
      Note: Group fields are not available to select.

      The Alphanumeric field is updated based on the type of field selected.

    3. In the Operator field, click [image] and select the required operator.
    4. In the Value field, enter the filter value.
    5. (Optional) Select Trim to remove any leading or trailing spaces, or leading zeroes from each record before it is filtered.
    6. (Optional) Select Case Sensitive to ensure the filtered content is case sensitive.

    By default, a record must match all specified conditions to be included in the results.

  8. To base the results on a record matching any of the conditions, click Match one.

    Tip: To remove a condition from the filter, click Delete Condition to the right of the required condition.
  9. Click Filter.

    The results appear.

  10. You can toggle between the results and the original file by clicking [image] in the Records field and select All or Filtered.
Parent topic: Filtering a Data File
Related reference
Preferences
Related information
Filter Operators


Filter Operators

Use the following operators in a filter condition:

Operator | Description
= | Equals the given text
!= | Not equal to the given text
> | Greater than the given text
>= | Greater than or equal to the given text
< | Less than the given text
<= | Less than or equal the given text
Contains | Contains the given text
Does not contain | Does not contain the given text
Is Valid | Contents of field is valid
Is Invalid | Contents of field is invalid
Parent topic: Filtering a Data File
Related information
Filter the Data File


Navigate a Data File

There are a number of techniques that enable you to navigate around the data file.

  1. From the Data File Tools window, click File > Open, or click [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required data file, then click Open.

    The Open Data File dialog box appears.

  3. If you are applying a layout, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select a structure (.dfs) file.
  4. Click Open File.

    The file is displayed on its own tab in the main window.

  5. You can navigate through the records using one of the following techniques:
    • To move through the records, in the Navigation group, click [image] and [image]; alternatively, use the cursor keys.
    • To move forwards or back a page, click [image] and [image].
      Note: Each page contains a maximum of 100 records.
    • To jump directly to a record, enter the record number in the Record Number field; alternatively, click the record in the Data File pane.
Parent topic: Viewing and Filtering Data Files
Related information
View File Information
Filtering a Data File
Show the Contents of a Data File in Hexadecimal
Select the Encoding for a Data File
Order a Data File using Indexed Keys


Show the Contents of a Data File in Hexadecimal

  1. From the Data File Tools window, click File > Open, or click [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required data file, then click Open.

    The Open Data File dialog box appears.

  3. If you are applying a layout, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select a structure (.dfs) file.
  4. Click Open File.

    The file is displayed on its own tab in the main window.

  5. In the Appearance group, click [image] (Toggle Hex).

    An additional pane is displayed beneath the Displaying Records pane, and if a record layout is being used, beneath the layout, both showing the equivalent hexadecimal digits for the selected data. Each pair of hex digits is arranged vertically; for example, when you edit ANSI data, an M is shown in hex as 4 with a D beneath.

    Tip: You can edit the hex values directly; see Edit a Record Using the Hexadecimal Values.
  6. To hide the Hex pane, click [image] (Toggle Hex) again.
Parent topic: Viewing and Filtering Data Files
Related tasks
Edit a Record Using Hexadecimal Values
Related information
View File Information
Filtering a Data File
Navigate a Data File
Select the Encoding for a Data File
Order a Data File using Indexed Keys


Select the Encoding for a Data File

By default, the file is displayed using ANSI encoding.

  1. From the Data File Tools window, click File > Open, or click [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required data file, then click Open.

    The Open Data File dialog box appears.

  3. If you are applying a layout, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select a structure (.dfs) file.
  4. Click Open File.

    The file is displayed on its own tab in the main window.

  5. In the Appearance group, click [image] beside ANSI, then select another encoding.

    The data file is displayed using the selected encoding.

Parent topic: Viewing and Filtering Data Files
Related information
View File Information
Filtering a Data File
Navigate a Data File
Show the Contents of a Data File in Hexadecimal
Order a Data File using Indexed Keys


Order a Data File using Indexed Keys

You can only perform this action with indexed files, where you can order the records by any of the keys configured when the data file was created.
  1. From the Data File Tools window, click File > Open, or click [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required data file, then click Open.

    The Open Data File dialog box appears.

  3. If you are applying a layout, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select a structure (.dfs) file.
  4. Click Open File.

    The file is displayed on its own tab in the main window.

  5. To order from the currently selected record, click [image] beside Primary Key, then select an alternate key to order your data file by.

    The data file is ordered (ascending order) using the key value.
    Note: The ordering starts at the currently selected record. For example, if you have the fifth record in a list selected when you sort on a different key, that record will remain fifth in the list, and the sixth record onwards will be sorted, in ascending order, using the key value. There will also be four records before the current record, which will be sorted in descending order using the key value. This may mean that not all records from the data file are displayed.
  6. To order based on a particular value (without having to select the record containing that value):
    1. Click [image] beside the key name.

      The Go to :<key-name> dialog box appears.

    2. Type the value on which to search, then click OK.
    Note: If you select a split key, type the required value(s) in the relevant component boxes.

    The data file is ordered (ascending order) using the key value(s).

  7. To re-display the original order of the data file, click [image], which is displayed just above the records, on the left-hand side.
Parent topic: Viewing and Filtering Data Files
Related information
View File Information
Filtering a Data File
Navigate a Data File
Show the Contents of a Data File in Hexadecimal
Select the Encoding for a Data File


Backing Up Data Files

Before you edit a data file, you can back up the current version when you open the file.

By default, a backup version of the file is created with today's date and time appended to the basename. You can change this at the point of saving the data file if you want to use a different versioning system for your backups.

  • Back Up a Data File
Parent topic: Using the Data File Editor


Back Up a Data File

  1. From the Data File Tools window, click File > Open, or click [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required data file, then click Open.

    The Open Data File dialog box appears.

  3. Click Backup.

    The Save dialog box appears.

  4. If required, edit the default name and location, then click Save.

    A copy of the data file is created.

Parent topic: Backing Up Data Files


Using the Structure File Editor

Note: This is a technology preview feature. It is being made available to allow you to edit test data and provide feedback on this new capability; however, this feature is not intended for the editing of production data and its use is not supported as such.

The Structure File Editor is a tabbed pane within the Data File Tools window that enables you to create and edit layouts within a structure file. The structure file can then be applied to a data file so that the Data File Editor is able to display the records within it in a way that makes them easier to view and edit.

Layouts are derived from the Data Division (level-01 fields and below in the File Section and Working Storage Section) of a COBOL program that uses the data file, and are created using the .idy file from the compiled program.

Structure files are not mandatory, but when applied to a data file, the fields within a record can be displayed in a structured way, making them easier to view and edit. If a structure file is not applied, the records are displayed unformatted, as long continuous strings of text, making them harder to view or update.

You can also use a structure file to save file details for file types that do not contain a file header. If you check the Save details check box on the Create New File dialog box, a .dfs file is saved containing the file details specified. This file is used to populate the File Details section the next time the data file is opened.

A structure file can contain both layouts and header details, but only layouts can be edited in the Structure File Editor.

  • Creating Structure Files and Layouts
    A structure file that contains layouts can contain one default layout, and one or more conditional layouts; both types of layout are optional.
  • Editing Structure Files and Layouts
    You can add, edit, or delete conditions in existing layouts, even after the structure file has been applied to a data file.
Parent topic: Data File Tools


Creating Structure Files and Layouts

A structure file that contains layouts can contain one default layout, and one or more conditional layouts; both types of layout are optional.

Conditional layouts contain conditions that you can attach to any non-group field within the layout. A condition is a true or false statement queried against the value of the field. If all conditions in the layout are true for a particular record, the record is displayed using that layout. If not all of the conditions are true, the record uses the default layout (or another conditional layout).

If you are using a structure file that does not contain a default layout, any records that cannot use a conditional layout from the structure file are displayed unformatted.

For records that could use more than one layout (that is, they match all conditions in more than one layout), the record uses the first layout possible, based on the order that the conditional layouts are displayed in the Selected Layouts pane.

  • Create a Structure File
Parent topic: Using the Structure File Editor
Related information
Editing Structure Files and Layouts


Create a Structure File

  1. From the Data File Tools window, click File > New.
  2. Select Structure File, then click OK.

    The Select an .idy fIle dialog box appears.

  3. Navigate to an .idy file for a compiled program that uses the data file that you plan to apply this structure file to, then click Open.
    Note: Programs must be compiled for debug in order to produce an .idy file.

    A new Structure tab is displayed in the Data File Tools window, containing the Data Division of the .idy file in the Available Layouts pane, and the Selected Layouts pane on the right-hand side, where your layout(s) will be displayed.

  4. To create a default layout, from the Available Layouts pane, right-click the required level entry and select New Default Layout.

    The new default layout appears in the Selected Layouts pane, and consists of the selected level entry and any sub-level entries.

    This is the layout that a record will use if there are no other layouts, or no other layouts that have criteria that matches with the record.

  5. To create a conditional layout, right-click another level entry in the Available Layouts pane, then select New Conditional Layout.

    The new conditional layout appears in the Selected Layouts pane.

    Note: You can differentiate the layouts by the icons [image] (Default) and [image] (Conditional).
  6. In the Selected Layouts pane, expand the layout to display the field on which to base the condition, then right-click it and select Add Condition.

    Note: Conditions cannot be applied to group fields within a layout.

    The Edit Condition dialog box appears.

  7. From the Condition section, select the operator in the Comparison field, and the value in the Values field.
  8. Click OK.
    Note: You can add more than one condition to a layout; any record must match all conditions in order to use the layout.
  9. On the File menu, select Save.

    The Save Layouts to File dialog box appears.

  10. In the Filename field, type the name of the structure file and click Save.
    Tip: If you save the file with the same basename and in the same location as the data file that it will be applied to, this structure file is automatically applied when you open the data file. Similarly, if you already use a structure file of the same basename and in the same location (for example, to store the file header details), select it again to append the layout information for the file.
Parent topic: Creating Structure Files and Layouts


Editing Structure Files and Layouts

You can add, edit, or delete conditions in existing layouts, even after the structure file has been applied to a data file.

You can also delete existing layouts from the structure file.

However, if you need to add a layout to an existing structure file, or the .idy used to create the structure file contains an updated file description, you must create a new structure file; you cannot add this new content to the existing structure file.

You are also unable to edit any file header details saved to the structure file.

  • Edit a Structure File
Parent topic: Using the Structure File Editor
Related information
Creating Structure Files and Layouts


Edit a Structure File

Note: You can only edit structure files that contain layouts. You cannot use these details to edit structure files that are used only to contain file header details.
  1. From the Data File Tools window, click File > Open, or click [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required structure file, then click Open.
    Tip: Click [image] beside Files of type, then select Structure Files (.dfs) to filter on structure files only.

    The structure file appears in the Structure File Editor.

  3. To delete a layout:
    1. Select any node within the layout, right-click and select Delete Layout.

      The layout is deleted.

  4. To add a condition to a layout:
    1. Right-click the node on which to add the condition, then select Add Condition.
      Note: Conditions can only be added to elementary items, not group items.

      The Edit Condition dialog box appears.

    2. Add the condition criteria, then click OK.

      The condition is added to the layout.

  5. To edit a condition within a layout:
    1. Right-click the node on which the condition is set, then select Edit Condition.

      The Edit Condition dialog box appears.

    2. Edit the condition criteria, then click OK.
  6. To delete a condition within a layout:
    1. Right-click the node on which the condition is set, then select Delete Condition.

      The condition is deleted from the layout.

  7. On the File menu, select Save.

    The Save dialog box appears.

  8. Click Save.
Parent topic: Editing Structure Files and Layouts


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: Data Files


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 TMP or TEMP 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:

Use: | To:
> | Create a new file
>> | Extend 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. If more than 1000 illegal duplicate keys are found, the rebuild aborts, because it considers the file attributes being used conflict with the data in the file to an extent that any results could be meaningless.
-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 | Quickly rebuilds index files using the index side file (IDXFORMAT"12")
-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.

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

If the data is found to be corrupt, the rebuild process will abort.

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 illegal 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} {/k|/u}

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:

Parameter: | Meaning:
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
10 | Rebuild has run out of memory

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).

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


File Handling

  • File Handling Reference
  • Fileshare Guide
Parent topic: Data Access


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
    Enterprise Developer provides MFSORT, a command line sort and merge utility, and MFJSORT, an emulator for DFSORT and SYNCSORT.
  • Sorting Files
    Use the environment variables to affect the running of a sort operation, and use the FCD codes and error messages to help troubleshoot failed sort operations.
  • Tracing File Operations
    Use the tracing file operations, which are provided to help in investigations into problems with file handling.
Parent topic: File Handling


Configuration File

The default filename for the File Handler configuration file is extfh.cfg but you can use a different filename by setting the EXTFH environment variable. For example:

set EXTFH=c:\mydir\test.cfg
sets the filename to c:\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:C:\\files\\acufiles]
FILESUFFIX=dat

[FOLDER:C:\\files\\rmfiles]
IDXFORMAT=21

sets all files in c:\files\acufiles that do not have a suffix to .dat, and all indexed files in c:\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 c:\files that sets IDXFORMAT 2, the subsequent setting of IDXFORMAT 21 would overwrite this.
Important: If you include a path to a file in the tag, you must enter the "\" character twice in order for the configuration file to be parsed correctly. For example, instead of
[C:\SITETEST\EXTFH\TEST2.dat]

you would need to enter

[C:\\SITETEST\\EXTFH\\TEST2.dat]

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 c:\files\mffiles, then if you have FOLDER tags for the following locations in your configuration file, the settings in them are applied:

  • c:\
  • c:\files
  • c:\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:

[c:\\acufiles\\file1.dat]
IDXFORMAT=17
[c:\\rmfiles\\file1.dat]
IDXFORMAT=21
Important: If you include a path to a file in the tag, you must enter the "\" character twice in order for the configuration file to be parsed correctly. For example, instead of
[C:\SITETEST\EXTFH\TEST2.dat]

you would need to enter

[C:\\SITETEST\\EXTFH\\TEST2.dat]

sets file1.dat in c:\files\acufiles to IDXFORMAT 17 and file1.dat in c:\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.

  • ACUFH
    Enables or disables the use of the ACU file handler (ACUFH).
  • 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.
  • ESACUFH
    Enables or disables the use of the ACUCOBOL-GT file handler (ACUFH) for data file operations running under Enterprise Server.
  • 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.
  • INDEXCOUNT
    The INDEXCOUNT option specifies the number of index nodes to be cached for an indexed file.
  • INDEXFILE
    The INDEXFILE option maps the name of the index file (for those indexed file formats that have a separate index file). This name can include full path information.
  • INSERTNULL
    When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTNULL option determines whether to insert NULL (x"00") characters before non-printable characters. The option also determines whether to strip out those NULL characters during READ operations.
  • INSERTTAB
    When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTTAB option determines whether to replace sequences of spaces with TAB characters.
  • INTEROP
    The INTEROP option determines which file handler is used for all file organizations in a given folder.
  • KEYCHECK
    The KEYCHECK option specifies whether the File Handler checks that the key definition defined in your application matches that of the indexed file you are opening.
  • KEYCOMPRESS
    The KEYCOMPRESS option specifies the type of key compression in use.
  • LOADONTOHEAP
    The LOADONTOHEAP option specifies whether the File Handler loads the file into memory before executing any I/O operations.
  • LOCKTYPE
    The LOCKTYPE option specifies the type of record locking in use.
  • LOG
    When LOG is set to ON, any unusual file-related situations, such as corrupted files, or automatic file recovery, are noted in a log file for later examination.
  • LOGFILENAME
    When the LOG option is active, the LOGFILENAME option specifies the name of the log file to produce.
  • LSEQNAMETYPE
    The LSEQNAMETYPE option determines if the FILESUFFIX option is used for line sequential files that do not explicitly specify a file extension.
  • LSFILETERM
    The option controls the behavior of the File Handler upon encountering the EOF character x"1a" when reading line sequential files.
  • LSRECDELIM
    The LSRECDELIM option specifies the characters to be used as the record delimiter in line sequential files.
  • MAINFRAMEPRINT
    For those files using WRITE AFTER ADVANCING or WRITE BEFORE ADVANCING, the MAINFRAMEPRINT option determines whether to use mainframe printer file format (filetype 11).
  • NAMEOPTIONS
    The NAMEOPTIONS option specifies whether the name you pass to the OPEN statement can contain File Handler options.
  • NFSFILELOCK
    The NFSFILELOCK option enables applications to detect record locks and file locks on UNIX NFS file systems.
  • NODESIZE
    The NODESIZE option specifies the size of the index nodes to use for an indexed file.
  • NOSEQCHECK
    The NOSEQCHECK option disables sequence-checking of keys in indexed files.
  • OPENINPUTSHARED
    The OPENINPUTSHARED option specifies whether files that you open for input, and for which you do not specify a LOCK MODE clause, can be shared by other users.
  • OSVSREWRITE
    The OSVSREWRITE option specifies whether to permit the WRITE statement for sequential files that are open for output. If so, these WRITE statements behave exactly like REWRITE statements.
  • READSEMA
    The READSEMA option specifies whether the system attempts to gain a semaphore for shared files when I/O operations are performed that do not modify the file.
  • READTODELIM
    The READTODELIM option specifies whether the file pointer is advanced to the next logical record in the file when reading in a record that is longer than the user data area. In these circumstances, the data record would effectively be truncated.
  • RELDATBUF
    The RELDATBUF option determines the size of buffer used when accessing a file with organization RELATIVE.
  • RELNAMETYPE
    The RELNAMETYPE option determines if the FILESUFFIX option is used for relative files that do not explicitly specify a file extension.
  • RELRECDELIM
    The RELRECDELIM option specifies the characters to be used as the record delimiter in fixed-length relative files.
  • RETRYLOCK
    The RETRYLOCK option indicates whether you wish to retry a READ operation that fails because the record is locked.
  • RETRYOPEN
    The RETRYOPEN option indicates whether you wish to retry an I/O operation that fails because the file is locked.
  • RETRYTIME
    The RETRYTIME option specifies whether the integer given in the RETRYLOCK and RETRYOPEN options specifies the number of attempts or the number of seconds.
  • RUNITLOCKDETECT
    The RUNITLOCKDETECT option specifies whether the File Handler checks whether a record has been locked by a separate OPEN statement issued from within the same run unit.
  • SEARCHONCREATE
    The SEARCHONCREATE parameter determines whether the File Handler searches each specified directory on a multi-directory path for a file with the same name as the one being created. This option applies only to files which are opened with OPEN OUTPUT.
  • SEQDATBUF
    The SEQDATBUF option determines the size of buffer to use when accessing a file with organization SEQUENTIAL.
  • SEQNAMETYPE
    The SEQNAMETYPE option determines if the FILESUFFIX option is used for sequential files that do not explicitly specify a file extension.
  • SKIPLOCK
    The SKIPLOCK option specifies whether to advance the current record pointer when a locked record is encountered during a sequential READ.
  • SPACEFILL
    The SPACEFILL option determines whether to fill with spaces that part of the record area beyond the data that is read when performing READ operations on line sequential or line advancing files.
  • STARTUNLOCK
    The STARTUNLOCK option determines whether a START operation will remove existing locks for files specified with single record locking; that is, without the WITH LOCK ON MULTIPLE RECORDS phrase.
  • STRIPSPACE
    The STRIPSPACE parameter determines whether to remove trailing space characters when performing WRITE or REWRITE operations on line sequential or line advancing files.
  • SUPPRESSADV
    The SUPPRESSADV option determines whether to ignore the ADVANCING phrase of the WRITE statement for record sequential files.
  • TRACE
    The TRACE option specifies whether Xfhtrace, the File Handler trace module, is enabled. The Xfhtrace module traces File Handler operations and logs all activity to a trace file. It is supplied to help you diagnose any problems you may have with COBOL files.
  • TRACEFILEEXTEND
    The TRACEFILEEXTEND option determines whether to write trace information to the end of the current trace file, if the trace file already exists. This option has no effect if TRACE is OFF.
  • TRACEFILENAME
    The TRACEFILENAME option specifies the name of the trace file to produce when the TRACE option is active.
  • USEVSAMKEYDEFS
    Use the keys defined in the catalog via the JCL and IDCAMS instead of the keys defined in the executing program.
  • WRITELINE
    The WRITELINE parameter determines whether mainframe or PC behavior is used for WRITE record.
  • WRITETHRU
    The WRITETHRU option determines whether modifications to a file are written out to disk immediately or buffered internally, either by the COBOL system or by the operating system, and flushed to disk at a later stage.
Parent topic: Configuration File


ACUFH

Enables or disables the use of the ACU file handler (ACUFH).

Data files detected to be of ACUCOBOL-GT type are directed to ACUFH; data files detected to not be of ACUCOBOL-GT type are processed as normal.

Syntax:

ACUFH = { ON } { OFF }

Parameters:

ON
All types of ACUCOBOL-GT data file are handled by the ACUFH.
OFF
No data files are handled by the ACUFH, even if INTEROP=ACU or IDXFORMAT=17 is set.

Properties:

Default: ON

Comments:

To use ACUFH when running under Enterprise Server, you must also set ESACUFH=ON; this option is OFF by default.

Parent topic: Configuration File Options
Related reference
ESACUFH


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
Btrieve with ANSI
6
Btrieve without ANSI
8
Large indexed file format
9
Indexed with single key, non-duplicate, key ordered records
10
Reserved
11
Mainframe print file format
12
Large indexed file format with separate index file
13
Reserved
14
Heap file
15
ESDS
16
Extended ESDS
17
Vision
18
Microsoft SQL Server
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


ESACUFH

Enables or disables the use of the ACUCOBOL-GT file handler (ACUFH) for data file operations running under Enterprise Server.

Syntax:

ESACUFH = { ON } { OFF }

Parameters:

ON
All types of ACUCOBOL-GT data file, running under Enterprise Server are handled by the ACUFH.
Note: ACUFH=ON must also be set before this setting takes effect.
OFF
No data files running under Enterprise Server are handled by the ACUFH, even if INTEROP=ACU or IDXFORMAT=17 is set.

Properties:

Default: OFF

Comments:

If this option is set to OFF, file operations for IDXFORMATs 17-21 are disabled.

Parent topic: Configuration File Options
Related reference
ACUFH


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: OFF

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: OFF

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
Btrieve with ANSI
6
Btrieve without ANSI
8
Large indexed file format
9
Indexed with single key, non-duplicate, key ordered records
10
Reserved
11
Mainframe print file format
12
Large indexed file format with separate index file
13
Reserved
14
Heap file
15
ESDS
16
Extended ESDS
17
Vision
18
Microsoft SQL Server
19
Oracle
20
DB2
21
RM
22-255
Reserved

Properties:

Default: 0

Comments:

By default, IDXFORMATs 17-21 are unavailable under Enterprise Server. You must ensure the ACUFH and ESACUFH configuration options are both set to ON to use these formats.

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 running your program under an Enterprise Server region, IDXFORMATs 17-21 are not supported.

If you are using Fileshare, IDXFORMATs 17 and 21 do not provide transaction processing capabilities by default. You must configure it on a file-by-file basis using the Virtual File Handler option (/ap) when specifying the file in your database reference file. For example, when you access the following file through Fileshare, it is additionally re-directed to the ACUFH file handler, where transactional support can be provided:
Fs /d dbase.ref /f acufile1.dat /ap ACUFH

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
Related reference
ACUFH
ESACUFH


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: 0

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.

Syntax:

IGNORELOCK = { ON } { INPUT } { OFF }

Parameters:

ON
Ignore all locks.
INPUT
Ignore locks only when reading files open for input.
OFF
Do not ignore locks.

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. It 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 c:\files\acufiles use the Vision file handler, and all file organizations in the folder c:\files\rmfiles use the RMFM file handler:

[XFH-DEFAULT]
[FOLDER:C:\\files\\acufiles]
INTEROP=ACU

[FOLDER:C:\\files\\rmfiles]
INTEROP=RM
Important: If you include a path to a file in the tag, you must enter the "\" character twice in order for the configuration file to be parsed correctly. For example, instead of
[C:\SITETEST\EXTFH\TEST2.dat]

you would need to enter

[C:\\SITETEST\\EXTFH\\TEST2.dat]

Comments:

ACUFH must be set ON for this option to have an effect. Under Enterprise Server, ESACUFH must also be set to ON for this option to have an effect.

In cases where the INTEROP and IDXFORMAT settings conflict, the INTEROP setting will override IDXFORMAT.

If you are only handling indexed files, you can also use the IDXFORMAT settings of 17 for Vision files and 21 for RM files.

INTEROP does not affect database file organizations.

The values for this option must be entered in upper case; invalid values are ignored.

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.

Parent topic: Configuration File Options
Related reference
IDXNAMETYPE
ACUFH
ESACUFH


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: ON

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: 0D0A.
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
The sharing mode is SHARING WITH ALL OTHER.
OFF
The sharing mode is SHARING WITH READ ONLY.

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: 0D0A.
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 bytes.

Properties:

Default: 4096 bytes
Parent topic: Configuration File Options


SEQNAMETYPE

The SEQNAMETYPE option determines if the FILESUFFIX option is used for sequential files that do not explicitly specify a file extension.

Syntax:

SEQNAMETYPE = { 0 } { 1 }

Parameters:

0
Do not apply the value of FILESUFFIX to sequential files that do not explicitly specify a file extension.
1
Apply the value of FILESUFFIX to sequential files that do not explicitly specify a file extension.

Properties:

Default: 0
Parent topic: Configuration File Options
Related reference
FILESUFFIX


SKIPLOCK

The SKIPLOCK option specifies whether to advance the current record pointer when a locked record is encountered during a sequential READ.

Syntax:

SKIPLOCK = { ON } { OFF }

Parameters:

ON
Advance the current record pointer when a locked record is encountered.
OFF
Do not advance the current record pointer.

Properties:

Default: OFF
Parent topic: Configuration File Options


SPACEFILL

The SPACEFILL option determines whether to fill with spaces that part of the record area beyond the data that is read when performing READ operations on line sequential or line advancing files.

Syntax:

SPACEFILL = { ON } { OFF }

Parameters:

ON
Fill the area with spaces.
OFF
Do not fill the area with spaces.

Properties:

Default: ON
Parent topic: Configuration File Options


STARTUNLOCK

The STARTUNLOCK option determines whether a START operation will remove existing locks for files specified with single record locking; that is, without the WITH LOCK ON MULTIPLE RECORDS phrase.

Syntax:

STARTUNLOCK = { ON } { OFF }

Parameters:

ON
A START operation will clear any existing lock for files specified with single record locking.
OFF
A START operation will not clear any existing lock for files specified with single record locking.

Properties:

Default: OFF

Comments:

This option is provided only for compatibility. Micro Focus recommend you do not change it.

Parent topic: Configuration File Options


STRIPSPACE

The STRIPSPACE parameter determines whether to remove trailing space characters when performing WRITE or REWRITE operations on line sequential or line advancing files.

Syntax:

STRIPSPACE = { ON } { OFF }

Parameters:

ON
Remove trailing space characters when performing WRITE or REWRITE operations on line sequential or line advancing files.
OFF
Do not remove trailing space characters when performing WRITE or REWRITE operations on line sequential or line advancing files.

Properties:

Default: ON
Parent topic: Configuration File Options


SUPPRESSADV

The SUPPRESSADV option determines whether to ignore the ADVANCING phrase of the WRITE statement for record sequential files.

Syntax:

SUPPRESSADV = { ON } { OFF }

Parameters:

ON
Ignore the ADVANCING phrase of the WRITE statement for record sequential files.
OFF
Do not ignore the ADVANCING phrase of the WRITE statement for record sequential files.

Properties:

Default: OFF
Parent topic: Configuration File Options


TRACE

The TRACE option specifies whether Xfhtrace, the File Handler trace module, is enabled. The Xfhtrace module traces File Handler operations and logs all activity to a trace file. It is supplied to help you diagnose any problems you may have with COBOL files.

Syntax:

TRACE = { ON } { OFF }

Parameters:

ON
Set tracing on either for the individual file or, if specified under the [XFH-DEFAULT] tag, for all files.
OFF
Do not produce a trace file.

Properties:

Default: OFF
Parent topic: Configuration File Options


TRACEFILEEXTEND

The TRACEFILEEXTEND option determines whether to write trace information to the end of the current trace file, if the trace file already exists. This option has no effect if TRACE is OFF.

Syntax:

TRACEFILEEXTEND = { ON } { OFF }

Parameters:

ON
Extend existing trace file when File Handler is first invoked.
OFF
Overwrite existing trace file when File Handler is first invoked.

Properties:

Default: OFF

Comments:

This parameter can be set globally only, that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


TRACEFILENAME

The TRACEFILENAME option specifies the name of the trace file to produce when the TRACE option is active.

Syntax:

TRACEFILENAME = filename

Parameters:

filename
Name of the trace file.

Properties:

Default: XFHTRACE.XFH

Comments:

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


USEVSAMKEYDEFS

Use the keys defined in the catalog via the JCL and IDCAMS instead of the keys defined in the executing program.

Syntax:

USEVSAMKEYDEFS = { ON } { OFF }

Parameters:

ON
Use the catalog's key definitions.
OFF
Use executing program's key definitions.

Properties:

Default: ON
Parent topic: Configuration File Options


WRITELINE

The WRITELINE parameter determines whether mainframe or PC behavior is used for WRITE record.

Syntax:

WRITELINE = { ON } { OFF }

Parameters:

ON
Mainframe behavior is used for WRITE record.
OFF
PC behavior is used for WRITE record.

Properties:

Default: OFF

Comments:

Set WRITELINE=OFF if you want PC print behavior for WRITELINE when using mainframe dialects.

Parent topic: Configuration File Options


WRITETHRU

The WRITETHRU option determines whether modifications to a file are written out to disk immediately or buffered internally, either by the COBOL system or by the operating system, and flushed to disk at a later stage.

Syntax:

WRITETHRU = { ON } { OFF }

Parameters:

ON
Write out all modifications to disk immediately.
OFF
Flush modifications later.

Properties:

Default: OFF

Comments:

You can obtain greater security, at the cost of significantly reduced performance, by setting this parameter to ON.

Parent topic: Configuration File Options


Operation Codes

  • Standard Operation Codes
  • Special Operation Codes
Parent topic: File Handling Reference


Standard Operation Codes

Not all operation codes are appropriate with all file organizations. Each operation code description includes a list of the file organizations for which it is valid.

  • Standard Operation Codes - Overview
  • CLOSE
  • COMMIT
  • DELETE
  • DELETE FILE
  • OPEN
  • READ
  • REWRITE
  • ROLLBACK
  • START
  • STEP
  • UNLOCK
  • WRITE
Parent topic: Operation Codes


Standard Operation Codes - Overview

Standard operation codes contain x"FA" in the most significant byte. The least significant byte indicates the specific operation.

CLOSE | Terminates the processing of a file.
COMMIT | Releases all record locks in all files held by a run unit.
DELETE | Logically removes a record from a file.
DELETE FILE | Physically removes the specified file from the physical devices on which it resides.
OPEN | Initiates the processing of files. It also performs checking and/or writing of labels and other I/O operations.
READ | For sequential access, makes available the next or previous logical record from a file. For random access, makes available a specified record from a disk file.
ROLLBACK | Releases all record locks in all files held by a run unit.
START | Provides a basis for logical positioning in a relative or indexed file, for subsequent retrieval of records.
STEP | Steps to the next physical record.
UNLOCK | Releases all record locks held by a run unit on a named file.
WRITE | Writes a new record to a file.
REWRITE | Replaces an existing record.

Not all operation codes are appropriate with all file organizations. Each operation code description includes a list of the file organizations for which it is valid, using the following key:

L | Line sequential
S | Record sequential (including vS)
R | Relative (including vR)
I | Indexed
vS | Record sequential variable format only
vR | Relative variable format only
Parent topic: Standard Operation Codes


CLOSE

Terminates the processing of files and reels/units with optional rewind and locking where appropriate. For record sequential files, the terms "reel" and "unit" are interchangeable; the treatment of sequential disk files is logically equivalent to the treatment of a file on tape or similar sequential media.

Opcode | Operation | File Type
80 | CLOSE | L S R I
81 | CLOSE WITH LOCK | L S R I
82 | CLOSE WITH NO REWIND | L S
84 | CLOSE REEL/UNIT | L S
85 | CLOSE REEL/UNIT FOR REMOVAL | L S
86 | CLOSE REEL/UNIT WITH NO REWIND | L S

Input Fields

None

Output Fields

fcd-file status File status
Parent topic: Standard Operation Codes


COMMIT

Releases all record locks in all files held by this run unit.

Opcode | Operation | File Types
DC | COMMIT (Unlock all files) | L S R I

Input Fields

None

Output Fields

None

Comments

This operation code requires an FCD for one of the files, but it can be completely empty.

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.

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 closed.
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 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.

Note: A properly returned file status code should be of the form 9/nnn - for example 9/009.

If you are viewing this in HEX, the HEX value of the file status code might look like 3232. If you are viewing this in decimal mode, the same code will have a value of 12850. To retrieve the correct run-time system error when you are in decimal mode, you need to convert the decimal value to HEX first and then extract the correct error code.

For example, if you receive 14657 as a value for the file status, this is a decimal value. This converts to 3941HEX. The second byte of this value, 41, must be converted to Decimal before looking at the RTS error code - thus this HEX value then represents an extended file status code of 9/065 which means the error code is COBRT065, a locked file status.

Parent topic: File Status
Related reference
Run-time System Error Messages
Related information
Fileshare Extended Status Codes


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
  • DFSORT and ICETOOL Emulation
  • SYNCSORT Emulation
  • Invoking Mfsort
  • Creating a Statistics Report
  • Example Commands
  • Error Messages
Parent topic: File Handling Reference


Introduction

This COBOL system provides the following methods of sorting and merging files:

Sorting Method | Description
The run-time system COBOL sort module | The default module that executes a SORT statement in your COBOL program. It can also be called directly using the CALL statement.
MFSORT utility | A utility that you can invoke from the command line, which enables you to sort and merge data files.
MFJSORT utility | An emulator of IBM’s DFSORT and ICETOOL utilities and SYNCSORT, which supports many of their major functions .
Note: MFJSORT and MFSORT are updated with new features on a regular basis but they do not offer a complete emulation of third-party sort utilities. If there are particular features that you need to use, please contact SupportLine to establish if they are available in MFJSORT or MFSORT.
Parent topic: Sort Utilities
Related concepts
DFSORT and ICETOOL Emulation
SYNCSORT Emulation
Related information
Invoking Mfsort
Creating a Statistics Report
Example Commands
Error Messages


DFSORT and ICETOOL Emulation

Note: MFJSORT and MFSORT are updated with new features on a regular basis but they do not offer a complete emulation of third-party sort utilities. If there are particular features that you need to use, please contact SupportLine to establish if they are available in MFJSORT or MFSORT.

Every reasonable effort has been made to ensure the accuracy of information relating to the emulation of IBM's DFSORT and ICETOOL at the time of publication; however, we cannot guarantee complete accuracy as these tools continue to be developed.

The MFSORT and MFJSORT utilities support the DFSORT EXEC PARM and program control statements that are detailed below. In addition, MFJSORT also supports the operators of the ICETOOL mainframe utility that are detailed below:

  • DFSORT EXEC PARM Options Emulation
  • DFSORT Program Control Emulation
  • ICETOOL Emulation
Parent topic: Sort Utilities
Related concepts
SYNCSORT Emulation
MFJSENGINE
Related information
Introduction
Invoking Mfsort
Creating a Statistics Report
Example Commands
Error Messages


DFSORT EXEC PARM Options Emulation

The MFSORT and MFJSORT utilities emulate the following PARM parameters of the EXEC statement:

  • PARM
Parent topic: DFSORT and ICETOOL Emulation


PARM

The following PARM parameters of the EXEC statement are supported.

>--,PARM=--.-CENTWIN=.-s-.---.--------<<
           |         +-f-+   |
           |                 |
           +-SIZE-.-n------+-+
           |      +-nK-----+ |
           |      +-nM-----+ |
           |      +-MAX----+ |
           |      +-MAX-m--+ |
           |      +-MAX-mK-+ |
           |      +-MAX-mM-+ |
           |                 |
           +-SKIPREC=z-------+
           |                 |
           +-STOPAFT=n-------+
           |                 |
           +-VLSHRT----------+
           |                 |
           +-Y2PAST=.-s-.----+
                    +-f-+
Note: VLSHRT is ON by default.

In this COBOL system, the following parameter fields are only parsed and ignored:

Parameter | Fields
ABEND | NOABEND |
ARESALL | (n | nK | nM)
AVGRLEN | n
BSAM |
CINV | NOCINV |
COBEXIT | (COB1 | COB2)
DSPSIZE | (MAX | n)
DYNALLOC | [ =( d | n | d, n | OFF)]
EFS | (name | NONE)
EQUALS | NOEQUALS |
E15 | =COB
E35 | =COB
FILSZ | (x | Ex | Ux)
HIRPMAX | (OPTIMAL | N | p%)
LIST | NOLIST |
LISTX | NOLISTX |
LOCALE | (name | CURRENT | NONE)
MSGDDN | ddname
MSGPRT | (ALL | CRITICAL | NONE)
ODMAXBF | (n | nK | nM)
OUTREL | NOOUTREL |
OVFLO | (RC0 | RC4 | RC16)
PAD | (RC0 | RC4 | RC16)
RC16 | (ABE)
RESALL | (n | nK | nM)
RESERVE | (n | nK | nM)
RESET | NORESET |
SDB | (LARGE | YES | INPUT | NO)
SOLRF | NOSOLRF |
SPANINC | (RC0 | RC4 | RC16)
SZERO | NOSZERO |
TRUNC | (RC0 | RC4 | RC16)
VERIFY | NOVERIFY |
VLLONG | NOVLLONG |
VLSCMP | NOVLSCMP |
NOVLSHRT |
VSAMEMT | NOVSAMEMT |
VSAMIO | NOVSAMIO |
WRKREL | NOWRKREL |
WRKSEC | NOWRKSEC |
ZDPRINT | NZDPRINT |

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: DFSORT EXEC PARM Options Emulation


DFSORT Program Control Emulation

The MFSORT and MFJSORT utilities emulate the following program control statements:

  • ALTSEQ
  • DEBUG
  • END
  • INCLUDE
  • INREC
  • MERGE
  • MODS
  • OMIT
  • OPTION
  • OUTFIL
  • OUTREC
  • RECORD
  • SORT
  • SUM
Parent topic: DFSORT and ICETOOL Emulation


ALTSEQ

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

                  +--,---+
                  V      |
>--ALTSEQ--CODE=-(.-fftt-.)------<<
Parent topic: DFSORT Program Control Emulation


DEBUG

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

          +------,-------+
          V              |
>--DEBUG--.--.---------.-.-----<<
             +-ABEND---+
             +-NOABEND-+
             +-ABSTP---+

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: DFSORT Program Control Emulation


END

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

>--END--<<
Parent topic: DFSORT Program Control Emulation


INCLUDE

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

>--INCLUDE--COND=-(logical-expression)-.----------.----------<<
                                       +-FORMAT=f-+

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

Limitations:

The maximum field length when comparing two fields that have the same format and the same length:

Format | MFJSORT | DFSORT and SYNCSORT
All | 256 | 256
CH (only when EBCDIC) | 128 | n/a

The maximum field length when comparing two fields that have the same format and differing lengths.

Format | MFJSORT | DFSORT and SYNCSORT
CH | 128 | 256
TS, CST | 19 | 256
ZD, OT, CTO, OL, CLO, LS, CSL | 18 | 256
FS, CSF | 18 | 32
PD | 10 | 255
PD0 | 8 | 8
BI, FI | 8 | 256
Parent topic: DFSORT Program Control Emulation


INREC

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

                      +--------,-------+
                      V                |
>---INREC--.-FIELDS=-(.-item-statement-.)----.---<<
           |                                 |
           |          +--------,----------+  |
           |          V                   |  |
           +-OVERLAY=(.-overlay-statement-.)-+

The following options for the item-statement field are supported:

                     +-------------,-----------------------------------------+
                     V                                                       |
>--item-statement=--(.--.----.-.-s-----------------------------------------.-.-)--<<
                        +-c:-+ |                                           |
                               +-p-----------------------------------------+
                               |                                           |
                               +-p,m.----.---------------------------------+
                               |    +-,a-+                                 |
                               |                                           |
                               +-p,m,format.-,edit-.-----------------------+
                               |           +-,to---+                       |
                               |                                           |
                               +-p,HEX-------------------------------------+
                               |                                           |
                               +-p,m,HEX-----------------------------------+
                               |                                           |
                               +-p,m,TRAN=LTOU-----------------------------+
                               |                                           |
                               +-p,m,TRAN=UTOL-----------------------------+
                               |                                           |
                               +-p,m,TRAN=ALTSEQ---------------------------+
                               |                                           |
                               +-p,m,Y2x(c)--------------------------------+
                               |                                           |
                               +-p,m,Y2xP----------------------------------+
                               |                                           |
                               +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                               |                                           |
                               +-p,m,date-format,DATEDIFF,p,m,date-format--+
                               |                                           |
                               +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following options for the overlay-statement field are supported:

                +-------------,-----------------------------------------+
                V                                                       |
>--OVERLAY--=--(.--.----.-.-s-----------------------------------------.-.-)--<<
                   +-c:-+ |                                           |
                          +-p,m---------------------------------------+
                          |                                           |
                          +-p,m.----.---------------------------------+
                          |    +-,a-+                                 |
                          |                                           |
                          +-p,m,format.-,edit-.-----------------------+
                          |           +-,to---+                       |
                          |                                           |
                          +-p,m,HEX-----------------------------------+
                          |                                           |
                          +-p,m,TRAN=LTOU-----------------------------+
                          |                                           |
                          +-p,m,TRAN=UTOL-----------------------------+
                          |                                           |
                          +-p,m,TRAN=ALTSEQ---------------------------+
                          |                                           |
                          +-p,m,Y2x(c)--------------------------------+
                          |                                           |
                          +-p,m,Y2xP----------------------------------+
                          |                                           |
                          +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                          |                                           |
                          +-p,m,date-format,DATEDIFF,p,m,date-format--+
                          |                                           |
                          +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

The following field values are supported, where applicable:

Field | Values
a (alignment) | D (doubleword aligned), F (fullword aligned), H (halfword aligned).
s (separation) | ADD, DATE, &DATE, DATE=(abcd), &DATE=(abcd), DATE1, &DATE1, DATE1P, &DATE1P, DATE2, &DATE2, DATE2P &DATE2P, DATE3, &DATE3, DATE3P, &DATE3P, DATEn, &DATEn, DATEn+r, &DATEn+r, DATEn-r, &DATEn-r, DATEn(c), &DATEn(c), DATEn(c)+r, &DATEn(c)+r, DATEn(c)-r, &DATEn(c)-r, DATEnP, DATEnP+r, &DATEnP+r, DATEnP-r, &DATEnP-r, DATENS, &DATENS, DATENS=(abc), &DATENS=(abc), DIVIDE, LITERALS, MULTIPLY, SEPERATOR CHARS, SEQNUM, SUBTRACT.

DATEDIFF limitations:

The valid length(m) and format(Y2x) combinations for each type of date field that can be used with DATEDIFF:

  • m,Y2X
  • 5,Y2T
  • 6,Y2T
  • 5,Y2W
  • 6,Y2W
  • 3,Y2U
  • 4,Y2V
  • 3,Y2X
  • 4,Y2Y

The maximum number of DATEDIFF operands permitted is 300.

Parent topic: DFSORT Program Control Emulation


MERGE

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

>--MERGE--FIELDS=-(logical-expression)--FORMAT=f-----<<
Note: The maximum size of a merge field is 256 characters.

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
FIELDS | (FILSZ=x | size=y]

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.
Parent topic: DFSORT Program Control Emulation


MODS

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

         +----------------,-------------------+
         V                                    |
>--MODS--.-.-E15-.=-(-n,m.----------------.-)-.-+-.-------------.----<<
           +-E35-+       +-,-.---.-.----.-+       +-HILEVEL=YES-+
           +-E61-+           +-s-+ +-,e-+

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
MODS | (E18=n, m, [s] [e])+[HILEVEL=YES] (E39=n, m, [s] [e])+[HILEVEL=YES]

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: DFSORT Program Control Emulation


OMIT

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

>--OMIT--COND=--(logical-expression)-.----------.----------<<
                                     +-FORMAT=f-+

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

Limitations:

The maximum field length when comparing two fields that have the same format and the same length:

Format | MFJSORT | DFSORT and SYNCSORT
All | 256 | 256
CH (only when EBCDIC) | 128 | n/a

The maximum field length when comparing two fields that have the same format and differing lengths.

Format | MFJSORT | DFSORT and SYNCSORT
CH | 128 | 256
TS, CST | 19 | 256
ZD, OT, CTO, OL, CLO, LS, CSL | 18 | 256
FS, CSF | 18 | 32
PD | 10 | 255
PD0 | 8 | 8
BI, FI | 8 | 256
Parent topic: DFSORT Program Control Emulation


OPTION

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

           +---------,-------------+
           V                       |
>--OPTION--.--.-CENTWIN---------.--.----------<<
              |                 |
              +-COPY------------+
              |                 |
              +-EFS=.-name-.----+
              |     +-NONE-+    |
              |                 |
              +-.-EQUALS---.----+
              | +-NOEQUALS-+    |
              |                 |
              +-OVFLO=.-RC0--.--+
              |       +-RC4--+  |
              |       +-RC16-+  |
                 |                 |
              +--SKIPREC=z------+
              |                 |
              +--STOPAFT=n------+
              |                 |
              +--Y2PAST=.-s-.---+
              |         +-f-+   |
              |                 |
              +-.-ZDPRINT--.----+
              | +-NZDPRINT-+    |
              |                 |
              +-VLSHRT----------+
Note: VLSHRT is ON by default.

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
ARESALL | (n | nK | nM)
ARESINV | (n | nK | nM)
AVGRLEN | n
CHALT |
NOCHALT |
CHECK |
NOCHECK |
CINV |
NOCINV |
CKPT |
COBEXIT | (COB1 | COB2)
DSA | n
DSPSIZE | MAX
DYNALLOC | [=(d | n | d,n | OFF)]
EXITCK | (STRONG | WEAK)
FILSZ | (x | Ex | Ux)
SIZE | (y | Ey | Uy)
HIRPMAX | (OPTIMAL | n | P%)
LIST |
NOLIST |
LISTX |
NOLISTX |
LOCALE | (name | CURRENT | NONE)
MAINSIZE | (n | nK | nM | MAX)
MOSIZE | (MAX | n | p%)
MSGDDN | ddname
MSGPRT | (ALL | NONE | CRITICAL)
PRINT |
NOBLKSET |
NOOUTREL |
NOOUTSEC |
NULLOUT | (RC0 | RC4 | RC16)
ODMAXBF | (n | nK | nM)
PAD | (RC0 | RC4 | RC16)
RESALL | (n | nK | nM)
RESET |
NORESET |
RESINV | (n | nK | nM)
SDB | (LARGE | YES | INPUT | NO)
SMF | (SHORT | FULL | NO)
SOLRF |
NOSOLRF |
SORTDD | cccc
SORTIN | ddname
SORTOUT | ddname
SPANINC | (RC0 | RC4 | RC16)
SZERO |
NOSZERO |
TRUNC | (RC0 | RC4 | RC16)
USEWKDD |
VERIFY |
NOVERIFY |
VLLONG |
NOVLLONG |
VLSCMP |
NOVLSCMP |
NOVLSHRT |
VSAMEMT |
NVSAMEMT |
VSAMIO |
NOVSAMIO |
WRKREL |
NOWRKREL |
WRKSEC |
NOWRKSEC |

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: DFSORT Program Control Emulation


OUTFIL

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

           +----------------------------,-----------------------------------+
           |                                                                |
           |             +---,----+                                         |
           V             V        |                                         |
>--OUTFIL--.--.--FNAMES=-.-ddname-.---------------------------------------.-.----------<<
              |                                                           |
              |         +---,-----+                                       |
              |         V         |                                       |
              +--FILES=-.-.-d---.-.---------------------------------------+
              |           +-dd--+                                         |
              |           +-OUT-+                                         |
              |                                                           |
              +--STARTREC=-n----------------------------------------------+
              |                                                           |
              +-ENDREC=-n-------------------------------------------------+
              |                                                           |
              |           +------,---------+                              |
              |           V                |                              |
              +--OUTREC=-(.-item-statement-.)-.----------.-.------------.-+
              |                               +-,VTOF----+ +-VFILL=byte-+ |
              |                               +-,CONVERT-+                |
              |            +-------,--------+                             |
              |            V                |                             |
              +--OVERLAY=-(.-item-statement-.)----------------------------+
              |                                                           |
              |                                                           |
              |                                                           |
              +-.-INCLUDE=-.-(-logical-expression-)-.---.-----------------+
              | |          +-ALL--------------------+   |                 |
              | |          +-NONE-------------------+   |                 |
              | |                                       |                 |
              | |                                       |                 |
              + +-OMIT=-.-(logical-expression-)-.-------+                 |
              |         +-ALL-------------------+                         |
              |         +-NONE------------------+                         |
              |                                                           |
              +--SAVE-----------------------------------------------------+
              |                                                           |
              +--FTOV-----------------------------------------------------+
              |                                                           |
              +--SPLIT----------------------------------------------------+
              |                                                           |
              +--LINES=n--------------------------------------------------+
              |                                                           |
              |           +--------,--------+                             |
              |           V                 |                             |
              +--HEADERn=-.-(-header-item-)-.-----------------------------+
              |                                                           |
              |            +-------,----------+                           |
              |            V                  |                           |
              +--TRAILERn=-.-(-trailer-item-)-.---------------------------+
              |                                                           |
              |            +-------,----------+                           |
              |            V                  |                           |
              +--SECTIONS=-.-(-section-item-)-.---------------------------|
              |                                                           |
              +--NODETAIL-------------------------------------------------|
              |                                                           |
              +--REMOVECC-------------------------------------------------|
              |                                                           |
              +--CONVERT--------------------------------------------------+
Note: The maximum number of OUTFILs is 2048.

The following options for the item-statement field are supported:

                     +-------------,-----------------------------------------+
                     V                                                       |
>--item-statement=--(.--.----.-.-s-----------------------------------------.-.-)--<<
                        +-c:-+ |                                           |
                               +-p-----------------------------------------+
                               |                                           |
                               +-p,m.----.---------------------------------+
                               |    +-,a-+                                 |
                               |                                           |
                               +-p,m,format.-,edit-.-----------------------+
                               |           +-,to---+                       |
                               |                                           |
                               +-p,HEX-------------------------------------+
                               |                                           |
                               +-p,m,HEX-----------------------------------+
                               |                                           |
                               +-p,m,TRAN=LTOU-----------------------------+
                               |                                           |
                               +-p,m,TRAN=UTOL-----------------------------+
                               |                                           |
                               +-p,m,TRAN=ALTSEQ---------------------------+
                               |                                           |
                               +-p,m,Y2x(c)--------------------------------+
                               |                                           |
                               +-p,m,Y2xP----------------------------------+
                               |                                           |
                               +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                               |                                           |
                               +-p,m,date-format,DATEDIFF,p,m,date-format--+
                               |                                           |
                               +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following field values are supported, where applicable:

Field | Values
a (alignment) | D (doubleword aligned), F (fullword aligned), H (halfword aligned).
s (separation) | ADD, DATE, &DATE, DATE=(abcd), &DATE=(abcd), DATE1, &DATE1, DATE1P, &DATE1P, DATE2, &DATE2, DATE2P &DATE2P, DATE3, &DATE3, DATE3P, &DATE3P, DATEn, &DATEn, DATEn+r, &DATEn+r, DATEn-r, &DATEn-r, DATEn(c), &DATEn(c), DATEn(c)+r, &DATEn(c)+r, DATEn(c)-r, &DATEn(c)-r, DATEnP, DATEnP+r, &DATEnP+r, DATEnP-r, &DATEnP-r, DATENS, &DATENS, DATENS=(abc), &DATENS=(abc), DIVIDE, LITERALS, MULTIPLY, SEPERATOR CHARS, SEQNUM, SUBTRACT.

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

The following options for the header item are supported:

              +-------------,--------------------+
              V                                  |
>--HEADERn=--(.--.----.-.-r------------------.-)-.--<<
                 +-c:-+ +-.-DATE----------.--+
                        | +-&DATE---------+  |
                        | +-DATE=(abcd)---+  |
                        | +-&DATE=(abcd)--+  |
                        | +-DATENS=(abc)--+  |
                        | +-&DATENS=(abc)-+  |
                        |                    |
                        +-.-TIME--.----------+
                        | +-&TIME-+          |
                        |                    |
                        +-.-PAGE--.----------+
                          +-&PAGE-+

The following options for a trailer item are supported:

               +-------------,----------------------------------+
               V                                                |
>--TRAILERn=--(.--.----.-.-r--------------------------------.-)-.--<<
                  +-c:-+ +-.-DATE----------.----------------+
                         | +-&DATE---------+                |
                         | +-DATE=(abcd)---+                |
                         | +-&DATE=(abcd)--+                |
                         | +-DATENS=(abc)--+                |
                         | +-&DATENS=(abc)-+                |
                         |                                  |
                         +-.-TIME--.------------------------+
                         | +-&TIME-+                        |
                         |                                  |
                         +-.-PAGE--.------------------------+
                         | +-&PAGE-+                        |
                         |                                  |
                         +-.-COUNT-------.------------------|
                         | +-COUNT=edit--+                  |
                         |                                  |
                         +-.-SUBCOUNT-----------.-----------|
                         | +-SUBCOUNT15---------+           |
                         | +-SUBCOUNT=(.-edit-.)+           |
                         |             +-to---+             |
                         |                                  |
                         +-.-TOTAL-.=-(p,m,f)---------------+
                         | +-TOT---+                        |
                         |                                  |
                         +-MIN=(p,m,f)----------------------+
                         |                                  |
                         +-MAX=(p,m,f)----------------------+
                         |                                  |
                         +-AVG=(p,m,f)----------------------+
                         |                                  |
                         +--.-SUB------.=-(p,m,f.-------.)--+
                         |  +-SUBTOT---+        +-,edit-+   |
                         |  +-SUBTOTAL-+        +-,to---+   |
                         |                                  |
                         +--SUBMIN=-(p,m,f.-------.)--------+
                         |                +-,edit-+         |
                         |                +-,to---+         |
                         |                                  |
                         +--SUBMAX=-(p,m,f.-------.)--------+
                         |                +-,edit-+         |
                         |                +-,to---+         |
                         |                                  |
                         +--SUBAVG=-(p,m,f.-------.)--------+
                         |                +-,edit-+         |
                         |                +-,to---+         |
                         +----------------------------------+
Note: See the Limitations section for the COUNT and SUBCOUNT values, and the TOTAL fields.

The following options for a sections item are supported:

              +------------------------------,--------------------------+
              |     +------------------------,------------------------+ |
              V     V                                                 | |
>--SECTIONS=-(.-p,m-.--.--------------------------------------------.-.-.)----<<
                       +-SKIP=.-P--.--------------------------------+
                       |      +-L--+                                |
                       |      +-nL-+                                |
                       |          +-----,-------+                   |
                       |          V             |                   |
                       +-HEADER3=(.-header-item-.)--.------------.--+
                       |                            +-,-PAGEHEAD-+  |
                       |           +-----,-------+                  |
                       |           V             |                  |
                       +-TRAILER3=(.-header-item-.)-----------------+

Limitations:

  • The maximum length of COUNT and SUBCOUNT values is 9 digits.
  • The maximum length of the TOTAL fields:
    TOTAL field formats | MFJSORT | DFSORT
    Length (m) | Digits (d) | Length (m) | Digits (d)
    ZD | 1-15 | *Maximum 18. | 1-15 | 15
    ZD | 16-31 | 16-31 | 31
    PD | 1-8 | 1-8 | 15
    PD | 9-16 | 9-16 | 31
    BI | 1-4 | 1-4 | 10
    BI | 5-8 | 5-8 | 20
    FI | 1-4 | 1-4 | 10
    FI | 5-8 | 5-8 | 20
    FL | 4 or 8 | 4 or 8 | 20
    CSF, FS | 1-15 | 1-15 | 15
    CSF, FS | 16-32 | 16-32 | 31

    * MFJSORT will display the total to the same amount of digits as specified in the length.

DATEDIFF limitations:

The valid length(m) and format(Y2x) combinations for each type of date field that can be used with DATEDIFF:

  • m,Y2X
  • 5,Y2T
  • 6,Y2T
  • 5,Y2W
  • 6,Y2W
  • 3,Y2U
  • 4,Y2V
  • 3,Y2X
  • 4,Y2Y

The maximum number of DATEDIFF operands permitted is 300.

Parent topic: DFSORT Program Control Emulation


OUTREC

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

                      +--------,-------+
                      V                |
>--OUTREC--.-FIELDS=-(.-item-statement-.)----.---<<
           |                                 |
           |          +--------,----------+  |
           |          V                   |  |
           +-OVERLAY=(.-overlay-statement-.)-+

The following options for the item-statement field are supported:

                     +-------------,-----------------------------------------+
                     V                                                       |
>--item-statement=--(.--.----.-.-s-----------------------------------------.-.-)--<<
                        +-c:-+ |                                           |
                               +-p-----------------------------------------+
                               |                                           |
                               +-p,m.----.---------------------------------+
                               |    +-,a-+                                 |
                               |                                           |
                               +-p,m,format.-,edit-.-----------------------+
                               |           +-,to---+                       |
                               |                                           |
                               +-p,HEX-------------------------------------+
                               |                                           |
                               +-p,m,HEX-----------------------------------+
                               |                                           |
                               +-p,m,TRAN=LTOU-----------------------------+
                               |                                           |
                               +-p,m,TRAN=UTOL-----------------------------+
                               |                                           |
                               +-p,m,TRAN=ALTSEQ---------------------------+
                               |                                           |
                               +-p,m,Y2x(c)--------------------------------+
                               |                                           |
                               +-p,m,Y2xP----------------------------------+
                               |                                           |
                               +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                               |                                           |
                               +-p,m,date-format,DATEDIFF,p,m,date-format--+
                               |                                           |
                               +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following options for the overlay-statement field are supported:

                +-------------,-----------------------------------------+
                V                                                       |
>--OVERLAY--=--(.--.----.-.-s-----------------------------------------.-.-)--<<
                   +-c:-+ |                                           |
                          +-p,m---------------------------------------+
                          |                                           |
                          +-p,m.----.---------------------------------+
                          |    +-,a-+                                 |
                          |                                           |
                          +-p,m,format.-,edit-.-----------------------+
                          |           +-,to---+                       |
                          |                                           |
                          +-p,m,HEX-----------------------------------+
                          |                                           |
                          +-p,m,TRAN=LTOU-----------------------------+
                          |                                           |
                          +-p,m,TRAN=UTOL-----------------------------+
                          |                                           |
                          +-p,m,TRAN=ALTSEQ---------------------------+
                          |                                           |
                          +-p,m,Y2x(c)--------------------------------+
                          |                                           |
                          +-p,m,Y2xP----------------------------------+
                          |                                           |
                          +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                          |                                           |
                          +-p,m,date-format,DATEDIFF,p,m,date-format--+
                          |                                           |
                          +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following field values are supported, where applicable:

Field | Values
a (alignment) | D (doubleword aligned), F (fullword aligned), H (halfword aligned).
s (separation) | ADD, DATE, &DATE, DATE=(abcd), &DATE=(abcd), DATE1, &DATE1, DATE1P, &DATE1P, DATE2, &DATE2, DATE2P &DATE2P, DATE3, &DATE3, DATE3P, &DATE3P, DATEn, &DATEn, DATEn+r, &DATEn+r, DATEn-r, &DATEn-r, DATEn(c), &DATEn(c), DATEn(c)+r, &DATEn(c)+r, DATEn(c)-r, &DATEn(c)-r, DATEnP, DATEnP+r, &DATEnP+r, DATEnP-r, &DATEnP-r, DATENS, &DATENS, DATENS=(abc), &DATENS=(abc), DIVIDE, LITERALS, MULTIPLY, SEPERATOR CHARS, SEQNUM, SUBTRACT.

DATEDIFF limitations:

The valid length(m) and format(Y2x) combinations for each type of date field that can be used with DATEDIFF:

  • m,Y2X
  • 5,Y2T
  • 6,Y2T
  • 5,Y2W
  • 6,Y2W
  • 3,Y2U
  • 4,Y2V
  • 3,Y2X
  • 4,Y2Y

The maximum number of DATEDIFF operands permitted is 300.

Parent topic: DFSORT Program Control Emulation


RECORD

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

>--RECORD--.-TYPE=-.-F-.--------------------.----<<
           |       +-V-+                    |
           +-.--------.--LENGTH=(L1,...,L3)-+
           | +-TYPE=F-+                     |
           +-.--------.--LENGTH=(L1,...,L7)-+
             +-TYPE=V-+
Parent topic: DFSORT Program Control Emulation


SORT

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

                    +---,---+                   +---------,------------+
                    V       |                   V                      |
>--SORT--FIELDS=-.-(.-p,m,f-.)----------------.-.--.-.-EQUALS---.---.--.----<<
                 |                            |    + +-NOEQUALS-+   |
                 |  +--,--------+             |    |                |
                 |  V           |             |    +-SKIPREC=z------+
                 +-(.-p,m,.---.-.)-,-FORMAT=f-+    +-STOPAFT=n------+
                 |        +-f-+               |    +-Y2PAST=-.-s-.--+
                 +-COPY-----------------------+    |         +-f-+  |
                                                   +-CENTWIN=-.-s-.-+
                                                              +-f-+
Note: The maximum size of a sort field is 256 characters.

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
FIELDS | CKPT DYNALLOC [=(d | n | d, n | OFF)] FILSZ = (x | Ex | Ux) SIZE = (y | Ey | Uy)

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.
Parent topic: DFSORT Program Control Emulation


SUM

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

                   +---,---+
                   V       |
>--SUM--FIELDS=-.-(.-p,m,f-.)----------------.----<<
                |                            |
                |  +--,--------+             |
                |  V           |             |
                +-(.-p,m,.---.-.)-,-FORMAT=f-+
                |        +-f-+               |
                +-NONE-----------------------+
Restriction: The maximum number of SUM fields is 600 and the maximum SUM field length is 18.

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.
Parent topic: DFSORT Program Control Emulation


ICETOOL Emulation

The MFJSORT utility supports the following ICETOOL operators.

Note: Not each operator is fully supported. There is no support for parameters which are not listed.
  • COPY
  • COUNT
  • DISPLAY
  • OCCUR
  • RANGE
  • SELECT
  • SPLICE
  • SORT
  • STATS
  • UNIQUE
Parent topic: DFSORT and ICETOOL Emulation


COPY

The following parameters of this ICETOOL operator are supported in MFJSORT:

                              +---,---+
                              V       |
>--COPY--FROM(indd)-.-.--TO-(-.-outdd-.-)-----------.-.----<<
                    | +-USING(xxxx)-----------------+ |
                    | |                             | |
                    | |      +----,--+              | |
                    | |      V       |              | |
                    | +-TO-(-.-outdd-.-)-USING(xxx)-+ |
                    |                                 |
                    +-.-------------.-----------------+
                    | +-VSAMTYPE(x)-+                 |
                    |                                 |
                    +-.--------.----------------------+
                      +-SERIAL-+

Limits and Restrictions:

Parameter | Restriction
outdd | Maximum outdd count is 10
LOCALE(name), LOCALE(CURRENT), and LOCALE(NONE) | These parameters are parsed but ignored.
Parent topic: ICETOOL Emulation


COUNT

The following parameters of this ICETOOL operator are supported in MFJSORT:

>-COUNT--FROM(indd)-.--.-------------.--.------<<
                    |  +-USING(xxxx)-+  |
                    |                   |
                    +-.-------------.---+
                    | +-VSAMTYPE(x)-+   |
                    |                   |
                    +-.------.----------+
                    | +-RC4--+          |
                    | +-RC12-+          |
                    |                   |
                    +-.-------------.---+
                      +-EMPTY-------+
                      +-NOTEMPTY----+
                      +-HIGHER(x)---+
                      +-LOWER(y)----+
                      +-EQUAL(v)----+
                      +-NOTEQUAL(w)-+

Limits and Restrictions:

Parameter | Restriction
LOCALE(name), LOCALE(CURRENT), and LOCALE(NONE) | These parameters are parsed but ignored.
Parent topic: ICETOOL Emulation


DISPLAY

The following parameters of this ICETOOL operator are supported in MFJSORT:

                          +-----------,--------------+
                          V                          |
>--DISPLAY--FROM(indd)--.-.-.--ON(p,m,f)-----------.-.-.----<<
                        |   +--ON(p,m,f,formatting-+   |
                        |   +--ON(p,m,HEX)---------+   |
                        |   +--ON(VLEN)------------+   |
                        |   +--ON(NUM)-------------+   |
                        |                              |
                        +-LIST(listdd)-----------------+
                        |                              |
                        | +------,--------------+      |
                        | V                     |      |
                        +-.-.-----------------.-.------+
                        |   +-TITLE('string')-+        |
                        |                              |
                        +-.------.---------------------+
                        | +-PAGE-+                     |
                        |                              |
                        +-.------------.---------------+
                        | +-DATE-------+               |
                        | +-DATE(abcd)-+               |
                        |                              |
                        +-.-----------.----------------+
                        | +-TIME------+                |
                        | +-TIME(abc)-+                |
                        |                              |
                        +-.-------.--------------------+
                        | +-BLANK-+                    |
                        | +-PLUS--+                    |
                        |                              |
                        | +----------,-----------+     |
                        | V                      |     |
                        +-.-.------------------.-.-----+
                        |   +-HEADER('string')-+       |
                        |   +-HEADER(NONE)-----+       |
                        |   +-NOHEADER---------+       |
                        |                              |
                        +-.----------.-----------------+
                        | +-LINES(n)-+                 |
                        |                              |
                        +-.-----------------.----------+
                        | +-TOTAL('string')-+          |
                        |                              |
                        +-.-------------------.--------+
                        | +-MINIMUM('string')-+        |
                        |                              |
                        +-.-------------------.--------+
                        | +-MAXIMUM('string')-+        |
                        |                              |
                        +-.-------------------.--------+
                        | +-AVERAGE('string')-+        |
                        |                              |
                        +-.----------.-----------------+
                        | +-LIMIT(n)-+                 |
                        |                              |
                        +-.-------------.--------------+
                        | +-VSAMTYPE(x)-+              |
                        |                              |
                        +-.----------.-----------------+
                        | +-WIDTH(n)-+                 |
                        |                              |
                        +-.--------------.-------------+
                        | +-BREAK(p.m.f)-+             |
                        |                              |
                        +-.-----------------.----------+
                        | +-BTITLE('string')+          |
                        |                              |
                        +-.-----------------.----------+
                        | +-BTOTAL('string')+          |
                        |                              |
                        +-.-------.--------------------+
                          +-UZERO-+

Limits and Restrictions:

Parameter | Restriction
ON | Maximum ON count of 20
HEADER('string') | Maximum string size of 50
LINES(n) | Range of n = 9-1000
WIDTH(n) | Range of n = 121-2048
TITLE('string') | Maximum TITLE('string') count is 3
Parent topic: ICETOOL Emulation


OCCUR

The following parameters of this ICETOOL operator are supported in MFJSORT:

                             +-----------,--------------+
                             V                          |
>--.-OCCUR--.--FROM(indd)--.-.-.-ON(p,m,f)------------.-.-.-----<<
   +-OCCURS-+              |   +-ON(p,m,f,formatting)-+   |
                           |   +-ON(p,m,HEX)----------+   |
                           |   +-ON(VLEN)-------------+   |
                           |   +-ON(VALCNT)-----------+   |
                           |                              |
                           +---LIST(listdd)---------------+
                           |                              |
                           | +-------,-------------+      |
                           | V                     |      |
                           +-.-.-----------------.-.------+
                           |   +-TITLE('string')-+        |
                           |                              |
                           +-.------.---------------------+
                           | +-PAGE-+                     |
                           |                              |
                           +-.------------.---------------+
                           | +-DATE-------+               |
                           | +-DATE(abcd)-+               |
                           |                              |
                           +-.-----------.----------------+
                           | +-TIME------+                |
                           | +-TIME(abc)-+                |
                           |                              |
                           +-.-------.--------------------+
                           | +-BLANK-+                    |
                           | +-PLUS--+                    |
                           |                              |
                           | +----------,-----------+     |
                           | V                      |     |
                           +-.-.------------------.-.-----+
                           |   +-HEADER('string')-+       |
                           |   +-HEADER(NONE)-----+       |
                           |   +-NOHEADER---------+       |
                           |                              |
                           +-.----------.-----------------+
                           | +-LINES(n)-+                 |
                           |                              |
                           +-.-------------.--------------+
                           | +-VSAMTYPE(x)-+              |
                           |                              |
                           +-.----------.-----------------+
                           | +-WIDTH(n)-+                 |
                           |                              |
                           +-.-------.--------------------+
                           | +-UZERO-+                    |
                           |                              |
                           +-.-----------.----------------+
                             +-ALLDUPS---+
                             +-NODUPS----+
                             +-HIGHER(x)-+
                             +-LOWER(y)--+
                             +-EQUAL(v)--+

Limits and Restrictions

Parameter | Restriction
ON | Maximum ON count of 20
HEADER('string') | Maximum string size of 50
LINES(n) | Range of n = 9-1000
WIDTH(n) | Range of n = 121-2048
TITLE('string') | Maximum TITLE('string') count is 3

The ALLDUPS/NODUPS/HIGHER(x)/LOWER(y)/EQUAL(v) parameter must be the last parameter specified.

Parent topic: ICETOOL Emulation


RANGE

The following parameters of this ICETOOL operator are supported in MFJSORT:

>--RANGE--FROM(indd)--.-.--ON(p,m,f)--.--------.----<<
                      | +--ON(VLEN)---+        |
                      |                        |
                      +-.-HIGHER(x)----------.-+
                      | +-LOWER(y)-----------+ |
                      | +-HIGHER(x)-LOWER(y)-+ |
                      | +-EQUAL(v)-----------+ |
                      | +-NOTEQUAL(w)--------+ |
                      |                        |
                      +-.---------------.------+
                        +--VSAMTYPE(x)--+

Limits and Restrictions:

Parameter | Restriction
ON | Only one ON is allowed
Parent topic: ICETOOL Emulation


SELECT

The following parameters of this ICETOOL operator are supported in MFJSORT:

>--SELECT--FROM(indd)--.-.--TO(outdd)-----------------.-.---------<<
                       | +--DISCARD(savedd)-----------+ |
                       | +--TO(outdd)-DISCARD(savedd)-+ |
                       |                                |
                       |   +---,-------+                |
                       |   V           |                |
                       +-.-.-ON(p,m,f)-.-.--------------+
                       | +-ON(VLEN)------+              |
                       |                                |
                       +-.-ALLDUPS---.------------------+
                       | +-NODUPS----+                  |
                       | +-HIGHER(x)-+                  |
                       | +-LOWER(y)--+                  |
                       | +-EQUAL(v)--+                  |
                       | +--FIRST----+                  |
                       | +--LAST-----+                  |
                       |                                |
                       +-.-------------.----------------+
                       | +-VSAMTYPE(x)-+                |
                       |                                |
                       +-.---------.--------------------+
                         +--UZERO--+

Limits and Restrictions:

Parameter | Restriction
ON | Maximum ON count of 20
ON and ALLDUPS|NODUPS|HIGHER|LOWER|EQUAL|FIRST|LAST | Mandatory keywords
Parent topic: ICETOOL Emulation


SPLICE

The following parameters of this ICETOOL operator are supported in MFJSORT:

                              +-----------+ +-----------+
                              v           | v           |
>-SPLICE-FROM(indd)-TO(outdd)-.-ON(p,m,f)-.-.-WITH(p,m)-.-.-----------------.-<<
                                                          |                 |
                                                          +-.----------.----+
                                                          | +-WITHALL--+    |
                                                          | +-WITHANY--+    |
                                                          | +-WITHEACH-+    |
                                                          |                 |
                                                          +-.------------.--+
                                                          | +-KEEPNODUPS-+  |
                                                          |                 |
                                                          +-.----------.----+
                                                          | +-KEEPBASE-+    |
                                                          |                 |
                                                          +-.-------------.-|
                                                          | +-USING(xxxx)-+ |
                                                          |                 |
                                                          +-.-------------.-+
                                                          | +-VSAMTYPE(x)-+ |
                                                          |                 |
                                                          +-.-------.-------+
                                                          | +-UZERO-+       |
                                                          |                 |
                                                          +-.----------.----+
                                                            +-VLENMAX--+
                                                            +-VLENOVLY-+

Limits and Restrictions

Parameter | Restriction
ON | ON count must be between 1 and 20
WITH | WITH count must be between 1 and 50
Parent topic: ICETOOL Emulation


SORT

The following parameters of this ICETOOL operator are supported in MFJSORT:

>--SORT--FROM(indd)--USING(xxxx)--.-.------------------.-.-----<<
                                  | |                  | |
                                  | |      +--,----+   | |
                                  | |      V       |   | |
                                  | +--TO(-.-outdd-.-)-+ |
                                  |                      |
                                  +-VSAMTYPE(x)----------+
                                  |                      |
                                  +-.--------.-----------+
                                    +-SERIAL-+

Limits and Restrictions:

Parameter | Restriction
outdd | Maximum outdd count is 10
LOCALE(name), LOCALE(CURRENT), and LOCALE(NONE) | These parameters are parsed but ignored.
Parent topic: ICETOOL Emulation


STATS

The following parameters of this ICETOOL operator are supported in MFJSORT:

                          +----,------+
                          V           |
>--STATS--FROM(indd)--.-.-.-ON(p,m,f)-.-.-.-----<<
                      | +-ON(VLEN)------+ |
                      |                   |
                      +-.-------------.---+
                        +-VSAMTYPE(x)-+
Parent topic: ICETOOL Emulation


UNIQUE

The following parameters of this ICETOOL operator are supported in MFJSORT:

                           +----,------+
                           V           |
>--UNIQUE--FROM(indd)--.-.-.-ON(p,m,f)-.-.-.-----<<
                       | +-ON(VLEN)------+ |
                       |                   |
                       +-.-------------.---+
                       | +-VSAMTYPE(x)-+   |
                       |                   |
                       +-.-------.---------+
                         +-UZERO-+
Parent topic: ICETOOL Emulation


SYNCSORT Emulation

Note: MFJSORT and MFSORT are updated with new features on a regular basis but they do not offer a complete emulation of third-party sort utilities. If there are particular features that you need to use, please contact SupportLine to establish if they are available in MFJSORT or MFSORT.
Every reasonable effort has been made to ensure the accuracy of information relating to the emulation of SYNCSORT at the time of publication; however, we cannot guarantee complete accuracy as this tool continues to be developed.

The MFSORT and MFJSORT utilities support the following emulation:

  • SYNCSORT EXEC PARM Options Emulation
  • SYNCSORT Program Control Emulation
Parent topic: Sort Utilities
Related concepts
DFSORT and ICETOOL Emulation
MFJSENGINE
Related information
Introduction
Invoking Mfsort
Creating a Statistics Report
Example Commands
Error Messages


SYNCSORT EXEC PARM Options Emulation

The MFSORT and MFJSORT utilities emulate the following PARM parameters of the EXEC statement:

  • PARM
Parent topic: SYNCSORT Emulation


PARM

The following PARM parameters of the EXEC statement are supported.

>--,PARM=--.-CENTWIN=.-s-.---.--------<<
           |         +-f-+   |
           |                 |
           +-SIZE-.-n------+-+
           |      +-nK-----+ |
           |      +-nM-----+ |
           |      +-MAX----+ |
           |      +-MAX-m--+ |
           |      +-MAX-mK-+ |
           |      +-MAX-mM-+ |
           |                 |
           +-SKIPREC=z-------+
           |                 |
           +-STOPAFT=n-------+
           |                 |
           +-VLSHRT----------+
           |                 |
           +-Y2PAST=.-s-.----+
                    +-f-+
Note: VLSHRT is ON by default.

In this COBOL system, the following parameter fields are only parsed and ignored:

Parameter | Fields
ABEND | NOABEND |
ARESALL | (n | nK | nM)
AVGRLEN | n
BSAM |
CINV | NOCINV |
COBEXIT | (COB1 | COB2)
DSPSIZE | (MAX | n)
DYNALLOC | [ =( d | n | d, n | OFF)]
EFS | (name | NONE)
ELAP |
EQUALS | NOEQUALS |
E15 | =COB
E35 | =COB
FILSZ | (x | Ex | Ux)
HIRPMAX | (OPTIMAL | N)
LIST | NOLIST |
LISTX | NOLISTX |
LOCALE | (name | CURRENT | NONE)
MSGDDN | ddname
MSGPRT | (ALL | CRITICAL | NONE)
ODMAXBF | (n | nK | nM)
OUTREL | NOOUTREL |
OVFLO | (RC0 | RC4 | RC16)
PAD | (RC0 | RC4 | RC16)
RC16 | (ABE)
RESALL | (n | nK | nM)
RESERVE | (n | nK | nM)
RESET | NORESET |
SDB | (LARGE | YES | INPUT | NO)
SOLRF | NOSOLRF |
SPANINC | (RC0 | RC4 | RC16)
SZERO | NOSZERO |
TRUNC | (RC0 | RC4 | RC16)
VERIFY | NOVERIFY |
VLLONG | NOVLLONG |
VLSCMP | NOVLSCMP |
NOVLSHRT |
VSAMEMT | NOVSAMEMT |
VSAMIO | NOVSAMIO |
VSCORE | value
VSCORET | value
WRKREL | NOWRKREL |
WRKSEC | NOWRKSEC |
ZDPRINT | NZDPRINT |

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: SYNCSORT EXEC PARM Options Emulation


SYNCSORT Program Control Emulation

The MFSORT and MFJSORT utilities emulate the following program control statements:

  • ALTSEQ
  • DEBUG
  • END
  • INCLUDE
  • INREC
  • MERGE
  • MODS
  • OMIT
  • OPTION
  • OUTFIL
  • OUTREC
  • RECORD
  • SORT
  • SUM
Parent topic: SYNCSORT Emulation


ALTSEQ

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
                  +--,---+
                  V      |
>--ALTSEQ--CODE=-(.-fftt-.)------<<
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


DEBUG

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
          +------,-------+
          V              |
>--DEBUG--.--.---------.-.-----<<
             +-ABEND---+
             +-NOABEND-+
             +-ABSTP---+

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
DEBUG | BSAM CFW NOCFW CTRx=n EFSDPAFT=(n)+ EFSDPBFR=(n)+ EQUCOUNT ESTAE NOESTAE NOASSIST

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


END

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
>--END--<<
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


INCLUDE

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
>--INCLUDE--COND=-(logical-expression)-.----------.----------<<
                                       +-FORMAT=f-+

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

Limitations:

The maximum field length when comparing two fields that have the same format and the same length:

Format | MFJSORT | DFSORT and SYNCSORT
All | 256 | 256
CH (only when EBCDIC) | 128 | n/a

The maximum field length when comparing two fields that have the same format and differing lengths.

Format | MFJSORT | DFSORT and SYNCSORT
CH | 128 | 256
TS, CST | 19 | 256
ZD, OT, CTO, OL, CLO, LS, CSL | 18 | 256
FS, CSF | 18 | 32
PD | 10 | 255
PD0 | 8 | 8
BI, FI | 8 | 256
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


INREC

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
                      +--------,-------+
                      V                |
>---INREC--.-FIELDS=-(.-item-statement-.)----.---<<
           |                                 |
           |          +--------,----------+  |
           |          V                   |  |
           +-OVERLAY=(.-overlay-statement-.)-+

The following options for the item-statement field are supported:

                     +-------------,-----------------------------------------+
                     V                                                       |
>--item-statement=--(.--.----.-.-s-----------------------------------------.-.-)--.---------.--<<
                        +-c:-+ |                                           |      +-convert-+
                               +-p-----------------------------------------+
                               |                                           |
                               +-p,m.----.---------------------------------+
                               |    +-,a-+                                 |
                               |                                           |
                               +-p,m,format.-,edit-.-----------------------+
                               |           +-,to---+                       |
                               |                                           |
                               +-p,HEX-------------------------------------+
                               |                                           |
                               +-p,m,HEX-----------------------------------+
                               |                                           |
                               +-p,m,TRAN=LTOU-----------------------------+
                               |                                           |
                               +-p,m,TRAN=UTOL-----------------------------+
                               |                                           |
                               +-p,m,TRAN=ALTSEQ---------------------------+
                               |                                           |
                               +-p,m,Y2x(c)--------------------------------+
                               |                                           |
                               +-p,m,Y2xP----------------------------------+
                               |                                           |
                               +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                               |                                           |
                               +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following options for the overlay-statement field are supported:

                +-------------,-----------------------------------------+
                V                                                       |
>--OVERLAY--=--(.--.----.-.-s-----------------------------------------.-.-)--<<
                   +-c:-+ |                                           |
                          +-p,m---------------------------------------+
                          |                                           |
                          +-p,m.----.---------------------------------+
                          |    +-,a-+                                 |
                          |                                           |
                          +-p,m,format.-,edit-.-----------------------+
                          |           +-,to---+                       |
                          |                                           |
                          +-p,m,HEX-----------------------------------+
                          |                                           |
                          +-p,m,TRAN=LTOU-----------------------------+
                          |                                           |
                          +-p,m,TRAN=UTOL-----------------------------+
                          |                                           |
                          +-p,m,TRAN=ALTSEQ---------------------------+
                          |                                           |
                          +-p,m,Y2x(c)--------------------------------+
                          |                                           |
                          +-p,m,Y2xP----------------------------------+
                          |                                           |
                          +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                          |                                           |
                          +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

The following field values are supported, where applicable:

Field | Values
a (alignment) | D (doubleword aligned), F (fullword aligned), H (halfword aligned).
s (separation) | ADD, DATE, &DATE, DATE=(abcd), &DATE=(abcd), DATE1, &DATE1, DATE1P, &DATE1P, DATE2, &DATE2, DATE2P &DATE2P, DATE3, &DATE3, DATE3P, &DATE3P, DATEn, &DATEn, DATEn+r, &DATEn+r, DATEn-r, &DATEn-r, DATEn(c), &DATEn(c), DATEn(c)+r, &DATEn(c)+r, DATEn(c)-r, &DATEn(c)-r, DATEnP, DATEnP+r, &DATEnP+r, DATEnP-r, &DATEnP-r, DATENS, &DATENS, DATENS=(abc), &DATENS=(abc), DIVIDE, LITERALS, MULTIPLY, SEPERATOR CHARS, SEQNUM, SUBTRACT.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


MERGE

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
>--MERGE--FIELDS=-(logical-expression)--FORMAT=f-----<<
Note: The maximum size of a merge field is 256 characters.

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
FIELDS | (FILSZ=x | size=y]

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


MODS

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
         +----------------,-------------------+
         V                                    |
>--MODS--.-.-E15-.=-(-n,m.----------------.-)-.-+-.-------------.----<<
           +-E18-+       +-,-.---.-.----.-+       +-HILEVEL=YES-+
           +-E35-+           +-s-+ +-,e-+

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
MODS | (E18=n, m, [s] [e])+[HILEVEL=YES] (E39=n, m, [s] [e])+[HILEVEL=YES]

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


OMIT

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
>--OMIT--COND=--(logical-expression)-.----------.----------<<
                                     +-FORMAT=f-+

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

Limitations:

The maximum field length when comparing two fields that have the same format and the same length:

Format | MFJSORT | DFSORT and SYNCSORT
All | 256 | 256
CH (only when EBCDIC) | 128 | n/a

The maximum field length when comparing two fields that have the same format and differing lengths.

Format | MFJSORT | DFSORT and SYNCSORT
CH | 128 | 256
TS, CST | 19 | 256
ZD, OT, CTO, OL, CLO, LS, CSL | 18 | 256
FS, CSF | 18 | 32
PD | 10 | 255
PD0 | 8 | 8
BI, FI | 8 | 256
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


OPTION

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
           +---------,-------------+
           V                       |
>--OPTION--.--.-CENTWIN---------.--.----------<<
              |                 |
              +-COPY------------+
              |                 |
              +-EFS=.-name-.----+
              |     +-NONE-+    |
              |                 |
              +-.-EQUALS---.----+
              | +-NOEQUALS-+    |
              |                 |
              +-OVFLO=.-RC0--.--+
              |       +-RC4--+  |
              |       +-RC16-+  |
                 |                 |
              +--SKIPREC=z------+
              |                 |
              +--STOPAFT=n------+
              |                 |
              +--Y2PAST=.-s-.---+
              |         +-f-+   |
              |                 |
              +-.-ZDPRINT--.----+
              | +-NZDPRINT-+    |
              |                 |
              +-VLSHRT----------+
Note: VLSHRT is ON by default.

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
ARESALL | (n | nK | nM)
ARESINV | (n | nK | nM)
AVGRLEN | n
CHALT |
NOCHALT |
CHECK |
NOCHECK |
CINV |
NOCINV |
CKPT |
COBEXIT | (COB1 | COB2)
DSA | n
DSPSIZE | MAX
DYNALLOC | [=(d | n | d,n | OFF)]
EXITCK | (STRONG | WEAK)
FILSZ | (x | Ex | Ux)
SIZE | (y | Ey | Uy)
HIRPMAX | (OPTIMAL | n | P%)
LIST |
NOLIST |
LISTX |
NOLISTX |
LOCALE | (name | CURRENT | NONE)
MAINSIZE | (n | nK | nM | MAX)
MOSIZE | (MAX | n | p%)
MSGDDN | ddname
MSGPRT | (ALL | NONE | CRITICAL)
PRINT |
NOBLKSET |
NOOUTREL |
NOOUTSEC |
NULLOUT | (RC0 | RC4 | RC16)
ODMAXBF | (n | nK | nM)
PAD | (RC0 | RC4 | RC16)
RESALL | (n | nK | nM)
RESET |
NORESET |
RESINV | (n | nK | nM)
SDB | (LARGE | YES | INPUT | NO)
SMF | (SHORT | FULL | NO)
SOLRF |
NOSOLRF |
SORTDD | cccc
SORTIN | ddname
SORTOUT | ddname
SPANINC | (RC0 | RC4 | RC16)
SZERO |
NOSZERO |
TRUNC | (RC0 | RC4 | RC16)
USEWKDD |
VERIFY |
NOVERIFY |
VLLONG |
NOVLLONG |
VLSCMP |
NOVLSCMP |
NOVLSHRT |
VSAMEMT |
NVSAMEMT |
VSAMIO |
NOVSAMIO |
WRKREL |
NOWRKREL |
WRKSEC |
NOWRKSEC |

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


OUTFIL

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
           +----------------------------,-----------------------------------+
           |                                                                |
           |             +---,----+                                         |
           V             V        |                                         |
>--OUTFIL--.--.--FNAMES=-.-ddname-.---------------------------------------.-.----------<<
              |                                                           |
              |         +---,-----+                                       |
              |         V         |                                       |
              +--FILES=-.-.-d---.-.---------------------------------------+
              |           +-dd--+                                         |
              |           +-OUT-+                                         |
              |                                                           |
              +--STARTREC=-n----------------------------------------------+
              |                                                           |
              +-ENDREC=-n-------------------------------------------------+
              |                                                           |
              |           +------,---------+                              |
              |           V                |                              |
              +--OUTREC=-(.-item-statement-.)-.----------.-.------------.-+
              |                               +-,VTOF----+ +-VFILL=byte-+ |
              |                               +-,CONVERT-+                |
              |            +-------,--------+                             |
              |            V                |                             |
              +--OVERLAY=-(.-item-statement-.)----------------------------+
              |                                                           |
              |                                                           |
              |                                                           |
              +-.-INCLUDE=-.-(-logical-expression-)-.---.-----------------+
              | |          +-ALL--------------------+   |                 |
              | |          +-NONE-------------------+   |                 |
              | |                                       |                 |
              | |                                       |                 |
              + +-OMIT=-.-(logical-expression-)-.-------+                 |
              |         +-ALL-------------------+                         |
              |         +-NONE------------------+                         |
              |                                                           |
              +--SAVE-----------------------------------------------------+
              |                                                           |
              +--FTOV-----------------------------------------------------+
              |                                                           |
              +--SPLIT----------------------------------------------------+
              |                                                           |
              +--LINES=n--------------------------------------------------+
              |                                                           |
              |           +--------,--------+                             |
              |           V                 |                             |
              +--HEADERn=-.-(-header-item-)-.-----------------------------+
              |                                                           |
              |            +-------,----------+                           |
              |            V                  |                           |
              +--TRAILERn=-.-(-trailer-item-)-.---------------------------+
              |                                                           |
              |            +-------,----------+                           |
              |            V                  |                           |
              +--SECTIONS=-.-(-section-item-)-.---------------------------|
              |                                                           |
              +--NODETAIL-------------------------------------------------|
              |                                                           |
              +--REMOVECC-------------------------------------------------|
              |                                                           |
              +--CONVERT--------------------------------------------------+
Note: The maximum number of OUTFILs is 2048.

The following options for the item-statement field are supported:

                     +-------------,-----------------------------------------+
                     V                                                       |
>--item-statement=--(.--.----.-.-s-----------------------------------------.-.-)--.---------.--<<
                        +-c:-+ |                                           |      +-convert-+
                               +-p-----------------------------------------+
                               |                                           |
                               +-p,m.----.---------------------------------+
                               |    +-,a-+                                 |
                               |                                           |
                               +-p,m,format.-,edit-.-----------------------+
                               |           +-,to---+                       |
                               |                                           |
                               +-p,HEX-------------------------------------+
                               |                                           |
                               +-p,m,HEX-----------------------------------+
                               |                                           |
                               +-p,m,TRAN=LTOU-----------------------------+
                               |                                           |
                               +-p,m,TRAN=UTOL-----------------------------+
                               |                                           |
                               +-p,m,TRAN=ALTSEQ---------------------------+
                               |                                           |
                               +-p,m,Y2x(c)--------------------------------+
                               |                                           |
                               +-p,m,Y2xP----------------------------------+
                               |                                           |
                               +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                               |                                           |
                               +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following field values are supported, where applicable:

Field | Values
a (alignment) | D (doubleword aligned), F (fullword aligned), H (halfword aligned).
s (separation) | ADD, DATE, &DATE, DATE=(abcd), &DATE=(abcd), DATE1, &DATE1, DATE1P, &DATE1P, DATE2, &DATE2, DATE2P &DATE2P, DATE3, &DATE3, DATE3P, &DATE3P, DATEn, &DATEn, DATEn+r, &DATEn+r, DATEn-r, &DATEn-r, DATEn(c), &DATEn(c), DATEn(c)+r, &DATEn(c)+r, DATEn(c)-r, &DATEn(c)-r, DATEnP, DATEnP+r, &DATEnP+r, DATEnP-r, &DATEnP-r, DATENS, &DATENS, DATENS=(abc), &DATENS=(abc), DIVIDE, LITERALS, MULTIPLY, SEPERATOR CHARS, SEQNUM, SUBTRACT.

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

Limitations:

  • The maximum length of COUNT and SUBCOUNT values is 9 digits.
  • The maximum length of the TOTAL fields:
    TOTAL field formats | MFJSORT | SYNCSORT
    Length (m) | Digits (d) | Length (m) | Digits (d)
    ZD | 1-15 | *Maximum 18. | 1-15 | 15
    ZD | 16-31 | 16-31 | 31
    PD | 1-8 | 1-8 | 15
    PD | 9-16 | 9-16 | 31
    BI | 1-4 | 1-4 | 10
    BI | 5-8 | 5-8 | 20
    FI | 1-4 | 1-4 | 10
    FI | 5-8 | 5-8 | 20
    FL | 4 or 8 | 4 or 8 | 20
    CSF, FS | 1-15 | 1-15 | 15
    CSF, FS | 16-32 | 16-32 | 31

    * MFJSORT will display the total to the same amount of digits as specified in the length.

Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


OUTREC

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
                      +--------,-------+
                      V                |
>--OUTREC--.-FIELDS=-(.-item-statement-.)----.---<<
           |                                 |
           |          +--------,----------+  |
           |          V                   |  |
           +-OVERLAY=(.-overlay-statement-.)-+

The following options for the item-statement field are supported:

                     +-------------,-----------------------------------------+
                     V                                                       |
>--item-statement=--(.--.----.-.-s-----------------------------------------.-.-)--.---------.--<<
                        +-c:-+ |                                           |      +-convert-+
                               +-p-----------------------------------------+
                               |                                           |
                               +-p,m.----.---------------------------------+
                               |    +-,a-+                                 |
                               |                                           |
                               +-p,m,format.-,edit-.-----------------------+
                               |           +-,to---+                       |
                               |                                           |
                               +-p,HEX-------------------------------------+
                               |                                           |
                               +-p,m,HEX-----------------------------------+
                               |                                           |
                               +-p,m,TRAN=LTOU-----------------------------+
                               |                                           |
                               +-p,m,TRAN=UTOL-----------------------------+
                               |                                           |
                               +-p,m,TRAN=ALTSEQ---------------------------+
                               |                                           |
                               +-p,m,Y2x(c)--------------------------------+
                               |                                           |
                               +-p,m,Y2xP----------------------------------+
                               |                                           |
                               +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                               |                                           |
                               +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following options for the overlay-statement field are supported:

                +-------------,-----------------------------------------+
                V                                                       |
>--OVERLAY--=--(.--.----.-.-s-----------------------------------------.-.-)--<<
                   +-c:-+ |                                           |
                          +-p,m---------------------------------------+
                          |                                           |
                          +-p,m.----.---------------------------------+
                          |    +-,a-+                                 |
                          |                                           |
                          +-p,m,format.-,edit-.-----------------------+
                          |           +-,to---+                       |
                          |                                           |
                          +-p,m,HEX-----------------------------------+
                          |                                           |
                          +-p,m,TRAN=LTOU-----------------------------+
                          |                                           |
                          +-p,m,TRAN=UTOL-----------------------------+
                          |                                           |
                          +-p,m,TRAN=ALTSEQ---------------------------+
                          |                                           |
                          +-p,m,Y2x(c)--------------------------------+
                          |                                           |
                          +-p,m,Y2xP----------------------------------+
                          |                                           |
                          +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                          |                                           |
                          +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following field values are supported, where applicable:

Field | Values
a (alignment) | D (doubleword aligned), F (fullword aligned), H (halfword aligned).
s (separation) | ADD, DATE, &DATE, DATE=(abcd), &DATE=(abcd), DATE1, &DATE1, DATE1P, &DATE1P, DATE2, &DATE2, DATE2P &DATE2P, DATE3, &DATE3, DATE3P, &DATE3P, DATEn, &DATEn, DATEn+r, &DATEn+r, DATEn-r, &DATEn-r, DATEn(c), &DATEn(c), DATEn(c)+r, &DATEn(c)+r, DATEn(c)-r, &DATEn(c)-r, DATEnP, DATEnP+r, &DATEnP+r, DATEnP-r, &DATEnP-r, DATENS, &DATENS, DATENS=(abc), &DATENS=(abc), DIVIDE, LITERALS, MULTIPLY, SEPERATOR CHARS, SEQNUM, SUBTRACT.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


RECORD

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
>--RECORD--.-TYPE=-.-F-.--------------------.----<<
           |       +-V-+                    |
           +-.--------.--LENGTH=(L1,...,L3)-+
           | +-TYPE=F-+                     |
           +-.--------.--LENGTH=(L1,...,L7)-+
             +-TYPE=V-+
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


SORT

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
                    +---,---+                   +---------,------------+
                    V       |                   V                      |
>--SORT--FIELDS=-.-(.-p,m,f-.)----------------.-.--.-.-EQUALS---.---.--.----<<
                 |                            |    + +-NOEQUALS-+   |
                 |  +--,--------+             |    |                |
                 |  V           |             |    +-SKIPREC=z------+
                 +-(.-p,m,.---.-.)-,-FORMAT=f-+    +-STOPAFT=n------+
                 |        +-f-+               |    +-Y2PAST=-.-s-.--+
                 +-COPY-----------------------+    |         +-f-+  |
                                                   +-CENTWIN=-.-s-.-+
                                                              +-f-+
Note: The maximum size of a sort field is 256 characters.

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
FIELDS | CKPT DYNALLOC [=(d | n | d, n | OFF)] FILSZ = (x | Ex | Ux) SIZE = (y | Ey | Uy)

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


SUM

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
                   +---,---+
                   V       |
>--SUM--FIELDS=-.-(.-p,m,f-.)----------------.----<<
                |                            |
                |  +--,--------+             |
                |  V           |             |
                +-(.-p,m,.---.-.)-,-FORMAT=f-+
                |        +-f-+               |
                +-NONE-----------------------+
Restriction: The maximum number of SUM fields is 600 and the maximum SUM field length is 18.

If required, use the SORTXSUM DD statement to write records that were deleted during a SUM process to a dataset. This occurs at the time of the SUM processing, and so will not undergo OUTREC, E35 or OUTFIL processing, which all occur after SUM processing.

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


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 or incomplete command, an error is produced.
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 concepts
DFSORT and ICETOOL Emulation
SYNCSORT Emulation
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 work file. 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 work file, 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 on the IBM Knowledge Center. 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, found on the IBM Knowledge Center.
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 "d:\netexpress\base\workarea\golf.dat"
         organization is relative
         access mode is random
         relative key is relative-key.
 data division.
 file section.
 fd members-file
     record contains 28 characters.
 01 members-record.
     03 members-number pic 9(6).
     03 members-lname pic x(10).
     03 members-fname pic x(10).
     03 members-handicap pic 9(2).

You can then use the following mfsort command to sort the file golf.dat on the field containing the membership number in ascending order:

mfsort sort fields(1,6,nu,a)
   use golf.dat record f,28 org rl
   give members.dat

The sorted version of the file is written to the file members.dat.

Parent topic: FIELDS Instruction


Defining Input and Output Files

You need to give instructions to define both the input and output files:

File Instructions
Input
USE input-file [record definition]
   [org organization] [key structure]
Output
GIVE output-file [record definition]
   [org organization] [key structure]

Notes:

  • For input files that are either variable length or indexed files, you do not need to specify RECORD, ORG or KEYcommands as the file characteristics can be deduced from the file itself.
  • If you omit any of the above instructions, the last specified values are used. Therefore, you need only specify values for the first file if the input and output files are all of the same type and format.
  • If the first file is variable length or indexed, you do not need to specify any of the values.
  • You can use embedded library names and environment variables when you specify input and output files, in the same way as you can when you specify them in ASSIGN clauses; for more information see the sections Library Names in Paths and Filename Mapping in the chapter Filenames.
  • You can redirect the output file generated by MFSORT to another filename as follows:
    • If you do not use the SYSOUT environment variable, it is written to a file named SYSOUT.
    • If you do specify the SYSOUT environment variable, you specify the filename to be written to.
  • RECORD Instruction
  • ORG Instruction
  • KEY Instruction
Parent topic: Instructions


RECORD Instruction

You use the RECORD instruction to specify the format and length of records in the:

  • Sort work file
  • Input and output files when the instruction follows the associated USE or GIVE instruction

The RECORD instruction takes the following form:

RECORD format,rec-len,max-len

where the parameters are:

Parameter | Description
format | The record format, one of: F - fixed-length records of length rec-len V - variable-length records with a minimum length of rec-len and a maximum length of max-len
rec-len | If format is set to F, the record length If format is set to V, the minimum record length
max-len | If format is set to V, the maximum record length

If you do not specify a RECORD instruction for the sort workfile, the format defaults to fixed record format, with the record size equal to the largest record specified in the USE or GIVE instructions.

You do not need to specify a RECORD instruction for input files that are either variable length or indexed files as the file characteristics can be deduced from the file itself.

You must use a RECORD instruction if the record size is greater than 256.

If you do not specify a max-len for a line sequential input file, mfsort assumes 256. If you exceed this, the output file will have the input records split into several records.

Parent topic: Defining Input and Output Files


ORG Instruction

The ORG instruction specifies the file organization, and can be one of:

ORG Instruction | File Organization
IX | indexed
RL | relative
SQ | sequential (default value)
LS | line sequential

You do not need to specify an ORG instruction for input files that are either variable length or indexed files as the file characteristics can be deduced from the file itself.

Parent topic: Defining Input and Output Files


KEY Instruction

The KEY instruction specifies the key structure for an indexed file. It is used when an output file is indexed and its key structure is not the same as that of the indexed input file.

The format of the KEY instruction is:

KEY ({start,length,ixkey},...)

where the parameters are:

start
The starting position of the key in a record, counting in bytes from 1
length
The number of bytes in the key
ixkey
One of:
P
Primary key (this must always be defined first)
A
Alternate key
AD
Alternate key with duplicates
C
Component of the last-specified primary or alternate key

You can repeat the KEY instruction as often as required to describe the entire key structure. Use commas to separate the parameters and parameter sets (start, length, ixkey).

You must define the keys in order of importance with the primary key first, followed by all its components if it is split, then the first alternate key and all of its components and so on.

The following example defines three keys:

KEY (4,5,p,10,5,c,20,2,ad,40,2,a,46,10,c)

where:

4,5,p,10,5,c | represents the first primary key which is split. Its first component starts at character position 4 with a length of 5 bytes and its second component starts at character position 10 with a length of 5 bytes.
20,2,ad | represents the second (alternate) key which can have duplicates and starts at character position 20 with a length of 2 bytes
40,2,a,46,10,c | represents the third key. This is a split alternate key, with the first component starting at character position 40 with a length of 2 bytes and the second component starting at character position 46 with a length of 10 bytes.
Parent topic: Defining Input and Output Files


Creating a Statistics Report

There are two ways in which you can produce a statistics report for a SORT operation:

  • If you are not running under mainframe emulation, you can create a statistical report by using the MFJSTATS environment variable.
    Note: Setting the environment variable MFJSTATS to ON creates a report containing statistics for the SORT that is displayed to SYSOUT. If a report file already exists for a previous SORT, the new statistics are appended to the end of the previous one. The syntax is MFJSTATS=ON.
  • If you are running under mainframe emulation, add the following to your JCL to create a spool output, in ASCII format, for the SORT operation:
    //MFJSTATS DD SYSOUT=*
Parent topic: Sort Utilities
Related concepts
DFSORT and ICETOOL Emulation
SYNCSORT Emulation
Related information
Introduction
Invoking Mfsort
Example Commands
Error Messages


Example Commands

This section gives some examples of mfsort commands and jobstreams.

You may find it helpful to refer to the Examples of DFSORT Job Streams section of your DFSORT Application Programming Guide.

  • Sorting Using More Than One File
  • Single File Sort Using INCLUDE and a Sub-string Comparison
  • Single File Sort Using Environment Variables
  • Transforming Records Using OUTREC
  • Sort Using OUTFIL for Complex Reporting
Parent topic: Sort Utilities
Related concepts
DFSORT and ICETOOL Emulation
SYNCSORT Emulation
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 TMP or TEMP 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 concepts
DFSORT and ICETOOL Emulation
SYNCSORT Emulation
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:

  • MFJSENGINE
    Determines which sort engine the utility MFJSORT is to emulate.
  • MFJSERET
    Determines the response to an unsuccessful sort, copy or merge operation.
  • MFJSSTRICTSORT
    Enables strict mainframe emulation behavior during a sort.
  • MFJSTATS
    Produces a report for the COBOL SORT operation.
  • MFJSWINDOW
    Determines the sliding or fixed century window.
  • SORTCOMPRESS
    Determines whether to compress each record in a SORT operation.
  • SORTSCHEME
    To increase performance of a SORT operation, configure SORT to retain more of the record information in memory.
  • SORTSPACE
    Determines the amount of memory allocated to internal workspace for SORT operations.
  • SORTTEMPSPACE
    Determines the amount of temporary memory allocated for SORT operations.
  • 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


MFJSENGINE

Determines which sort engine the utility MFJSORT is to emulate.

Use this variable with Enterprise Server only.

Parameters

DFSORT
Emulates DFSORT
SYNCSORT
Emulates SYNCSORT

The default is DFSORT.

Example

Parent topic: SORT Environment Variables
Related concepts
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


MFJSERET

Determines the response to an unsuccessful sort, copy or merge operation.

If this environment variable is not set, an unsuccessful operation and its program will terminate with an unrecoverable error (return code 16).

Parameters

ABEND
The operation will abend and its program will continue instead of terminating with an unrecoverable error (return code 16)

The default is that the variable is not set.

Example

MFJSERET=ABEND
Parent topic: SORT Environment Variables
Related concepts
MFJSENGINE
MFJSTATS
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


MFJSSTRICTSORT

Enables strict mainframe emulation behavior during a sort.

Parameters

ON/OFF
Enables or disables the following mainframe behavior:
  • All JCL statements must contain a SYSOUT parameter, otherwise they will abend.
  • Modification of a ZD number with value 0 through INREC or OUTREC processing now keeps its sign value.
  • Records that are shorter than the output file's LRECL will be padded with low-values instead of spaces.
  • Input RECFM is identical to the output RECFM or OUTFIL RECFM (unless FTOV or VTOF/CONVERT has been specified), otherwise it errors with return code 16.

The default is OFF.

Example

MFJSSTRICTSORT=ON
Parent topic: SORT Environment Variables
Related concepts
MFJSENGINE
MFJSTATS
MFJSERET
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


MFJSTATS

Produces a report for the COBOL SORT operation.

Parameters

ON
The report is displayed to SYSOUT. If a report file already exists for a previous SORT operation, the new report is appended to it.
OFF
A report is not produced.

The default value is OFF.

Example

MFJSTATS=ON

Comments

If you are running a COBOL program with a SORT statement in a non-mainframe environment, set MFJSTATS=ON and in the same command prompt, run your COBOL program.

In a mainframe environment, if you run a COBOL program from your JCL, and that JCL uses COBOL syntax, you need to add //MFJSTATS DD SYSOUT=* to your JCL card.

Parent topic: SORT Environment Variables
Related concepts
MFJSENGINE
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS
Related reference
Creating a Statistics Report


MFJSWINDOW

Determines the sliding or fixed century window.

Use this environment variable for Y2K compatibility, when two-digit year values are used.

Parameters

To set a sliding century window, set a value between 0 and 100. For example, a value of 80 would set a century window of 1931-2030 in 2011, 1932-2031 in 2012, and so on.

To set a fixed century window, set a value between 1000 and 3000. For example, a value of 1973 would set a century window of 1973-2072.

The default is a sliding value of 80 when emulating DFSORT, and a default value of 0 when emulating SYNCSORT. A value of 0 equates to a century window, starting in the current year.

Example

MFJSWINDOW=25

Comments

You can use this environment variable instead of the Y2PAST sort option.

Parent topic: SORT Environment Variables
Related concepts
MFJSENGINE
MFJSTATS
MFJSERET
MFJSSTRICTSORT
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


SORTCOMPRESS

Determines whether to compress each record in a SORT operation.

When SORTCOMPRESS is set, run-length encoding of sort records results in much better performance when records contain multiple repeated characters.

Parameters

0
No compression.
Any number not equal to 0
Compression of records.

The default value is 0.

Example

SORTCOMPRESS=5
Parent topic: SORT Environment Variables
Related concepts
MFJSENGINE
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
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
MFJSENGINE
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
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.

If you are receiving COBRT105 Memory allocation error (Fatal) errors during your SORT operations, you should set SORTTEMPSPACE, and reduce the value of SORTSPACE; see SORTTEMPSPACE for more details.

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
MFJSENGINE
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
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 set SORTSPACE to a smaller value. Memory is then allocated in chunks of the size specified by SORTSPACE, until it has allocated the value set by SORTTEMPSPACE.

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
MFJSENGINE
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
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
MFJSENGINE
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
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
MFJSENGINE
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
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:

  • SORT011U SYSIN dataset value missing
  • SORT012U SYSIN dataset value missing
  • SORT013U I/O error on dataset value
  • SORT014U Status = value
  • SORT015U Command statement error(s) detected
    The sort will not execute because of errors found during the parsing of the command.
  • SORT019I Key length truncated to 4096 bytes
  • SORT020U SORT(EXTSM) failed - sort engine status = Value
    An unexpected failure occured after the sort had been initiated. This message indicates the returned sort file status value.
  • SORT032I Number records sorted
  • SORT033I Number records merged
  • SORT034I Number records copied
  • SORT036U SORTIN record length missing or invalid
    You did not specify a record length in the RECORD instruction, or else you specified an invalid length.
  • SORT037U SYSIN RECFM value invalid
  • SORT038U SORTIN RECFM value invalid
    The record format in the RECORD instruction for the input file is invalid.
  • SORT039U SORTOUT RECFM value invalid
    The record format in the RECORD instruction for the output file is invalid.
  • SORT040U SORT terminated by E15 Operator
    The user exit routine E15 has terminated the sort process.
  • SORT041U SORT terminated by E35 Operator
    The user exit routine E35 has terminated the sort process.
  • SORT042U Memory allocation failure
    The mfsort utility was unable to allocate the required memory.
  • SORT043U Too many OUTFIL files specified
    You have specified too many files in the OUTFIL option.
  • SORT044U Too many USE files specified
    You have specified too many files in the USE instruction.
  • SORT045U Too many GIVE files specified
    You have specified too many files in the GIVE instruction.
  • SORT050U ICETOOL input file not found
    The file that is to be sorted has not been found.
  • SORT051U ICETOOL output file not found
    The definition for the output file has not been found.
  • SORT090U SORT terminated - missing SYSOUT
    No catalog entry has been found for the SYSOUT file.
  • SORT091U SORT terminated - missing SYSIN
  • SORT092U SORT terminated - missing SORTOUT
  • SORT093U SORT terminated - missing SORTIN or SORTIN01
  • SORT094U SORT terminated - missing SORTOFvalue
  • SORT095U SORT terminated - Bad data in CHANGE field
    Please see the CHANGE and DFSORT documentation on the IBM web site for further details.
  • SORT096U SORT terminated - missing FNAMES dataset value
    Please see the FNAMES and DFSORT documentation on the IBM web site for further details.
Parent topic: Mfsort Error Messages


SORT011U SYSIN dataset value missing

Parent topic: Messages 0001 to 0099


SORT012U SYSIN dataset value missing

Parent topic: Messages 0001 to 0099


SORT013U I/O error on dataset value

Parent topic: Messages 0001 to 0099


SORT014U Status = value

Parent topic: Messages 0001 to 0099


SORT015U Command statement error(s) detected

The sort will not execute because of errors found during the parsing of the command.
Parent topic: Messages 0001 to 0099


SORT019I Key length truncated to 4096 bytes

Parent topic: Messages 0001 to 0099


SORT020U SORT(EXTSM) failed - sort engine status = Value

An unexpected failure occured after the sort had been initiated. This message indicates the returned sort file status value.

Resolution:

Investigate the file status. See the topic File Status.

Parent topic: Messages 0001 to 0099
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


SORT090U SORT terminated - missing SYSOUT

No catalog entry has been found for the SYSOUT file.
Parent topic: Messages 0001 to 0099


SORT091U SORT terminated - missing SYSIN

Parent topic: Messages 0001 to 0099


SORT092U SORT terminated - missing SORTOUT

Parent topic: Messages 0001 to 0099


SORT093U SORT terminated - missing SORTIN or SORTIN01

Parent topic: Messages 0001 to 0099


SORT094U SORT terminated - missing SORTOFvalue

Parent topic: Messages 0001 to 0099


SORT095U SORT terminated - Bad data in CHANGE field

Please see the CHANGE and DFSORT documentation on the IBM web site for further details.
Note: Refer to DFSORT and ICETOOL Emulation for details of the DFSORT syntax supported in Enterprise Developer
Parent topic: Messages 0001 to 0099
Related tasks
DFSORT ICETOOL and SYNCSORT Emulation


SORT096U SORT terminated - missing FNAMES dataset value

Please see the FNAMES and DFSORT documentation on the IBM web site for further details.
Note: Refer to DFSORT and ICETOOL Emulation for details of the DFSORT syntax supported in Enterprise Developer
Parent topic: Messages 0001 to 0099
Related tasks
DFSORT ICETOOL and SYNCSORT Emulation


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
  • Trace Player
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
  • Replay a sequence of file handling operations, using Trace Player
Parent topic: Tracing File Operations
Related information
Configuring Tracing and Logging
Dynamic Tracing
Trace Player


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=c:\trace\mftracefile.xfh
TRACEFILEEXTEND=ON
LOG=ON
LOGFILENAME=c:\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 option FILEMAXSIZE=8 (this is the default value).
Parent topic: Tracing File Operations
Related information
Introduction
Dynamic Tracing
Trace Player


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
Trace Player


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

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_MODIFY_TRACE and MFFH_MODIFY_DISABLE.

Parent topic: Dynamic Tracing
Related information
Using the FCD to Control Tracing


Trace Player

You can use the Trace Player to read and optionally replay the tracing information created when you have file operation tracing configured on. Tracing information is stored for one or more processes, with each process identified as a separate session. An operation trace consists of the I/O number (a number starting from 1 giving the position of the operation in the sequence of operations), the session ID, the opcode, file status resulting from the call and the name of the file. Additional information can optionally be displayed.

There are various ways to use the Trace Player:

  • View all the operations that were traced.
  • Replay all the operations across all sessions in I/O number order. All the files must be available in their original states.
  • Replay all the operations in one session in I/O number order.
  • Run a script to replay each session in session order. All the files must be available in their original states. The absolute order of operations across sessions might not be the same as when they were originally recorded.
  • Run the Trace Player from the Command Line
  • Examples
Parent topic: Tracing File Operations
Related information
Introduction
Configuring Tracing and Logging
Dynamic Tracing


Run the Trace Player from the Command Line

The format of the command line is:

cobfhrepro2/cobfhrepro3 [options]

Use cobfhrepro2 when you are using the FCD2 data structure and cobfhrepro3 when you are using FCD3.

The options specified on the command line define the operation to be carried out by the Trace Player. The following options are available:

num | Replays all the operations in one session, where num is the session ID. If num = 0, all the operations in all the sessions are replayed.
/a | Displays arguments; use in conjunction with /d
/d | Displays the trace information for each operation in I/O number order
/eop-num | Ends the replay at the I/O number op-num
/f | Displays the files needed for a replay
/nfilename | Trace a specific file
/pop-num | Pauses the replay at the I/O number op-num; press Enter to continue
/t | Displays only operations that fail and final status

If you run the Trace Player with no options, it creates the script that plays back each session in session order and informs you of the script's name. You must do this before every invocation of the script.

Parent topic: Trace Player
Related information
Examples


Examples

Here are some examples of typical output.

Example /d output

 I/O     Sess  Op  Opcode   Act   Exp   Filename                       O
Number    Id  Code Desc     Stat  Stat                                 K
-------- ---- ---- -------- ----- ----- ------------------------------ -
00000001 0001 FA02 Open      \    0\0   .\CATALOG.DAT
00000002 0001 FAF6 Read Ran  \    0\0   .\CATALOG.DAT
00000003 0001 FA02 Open      \    0\0   .\CATALOG.DAT

Example /d /a output

 I/O     Sess  Op  Opcode   Act   Exp   Filename                       O
Number    Id  Code Desc     Stat  Stat                                 K
-------- ---- ---- -------- ----- ----- ------------------------------ -
00000001 0001 FA02 Open      \    0\0   .\CATALOG.DAT
  fcd-version. 00   organisation 02   access-mode. 88   open.mode... 80
  opt2........ 20   shr2........ 08   shr......... 84   opt......... 20
  osp......... 80   file-format. 08   flags1...... 03   misc........ 10

RBA =000000000000  Rec Len = 010476
Session-id = 000000000000  FS-file-id =  000000000000

00000002 0001 FAF6 Read Ran  \    0\0   .\CATALOG.DAT
  fcd-version. 00   organisation 02   access-mode. 88   open.mode... 02
  opt2........ 20   shr2........ 08   shr......... 84   opt......... 20
  osp......... 80   file-format. 08   flags1...... 03   misc........ 10

RBA =000000000000  Rec Len = 010476
Session-id = 000000000000  FS-file-id =  000000000000

00000003 0001 FA02 Open      \    0\0   D:\Catalogs\TempOLFiles\Catalo
  fcd-version. 00   organisation 02   access-mode. 88   open.mode... 80
  opt2........ 20   shr2........ 08   shr......... 84   opt......... 20
  osp......... 80   file-format. 08   flags1...... 03   misc........ 10

RBA =000000000000  Rec Len = 010476
Session-id = 000000000000  FS-file-id =  000000000000

Example replay output

 I/O     Sess  Op  Opcode   Act   Exp   Filename                       O
Number    Id  Code Desc     Stat  Stat                                 K
-------- ---- ---- -------- ----- ----- ------------------------------ -
00000001 0001 FA02 Open     0\0   0\0   .\CATALOG.DAT -
00000002 0001 FAF6 Read Ran 0\0   0\0   .\CATALOG.DAT -
00000003 0001 FA02 Open     0\0   0\0   .\CATALOG.DAT -

Act Stat is the actual status returned when the Trace Player is run. Exp Stat is the status returned when the trace was recorded. In theory these two should be the same but in practice, they can be different. Act Stat is blank when you do a display because there is no actual status.

Parent topic: Trace Player
Related information
Run the Trace Player from the Command Line


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.
  • 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: File Handling


Introduction

  • Overview
  • How Fileshare Works
Parent topic: Fileshare Guide
Related information
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
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
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 Named Shared Memory protocol (CCISM) the default:
    /cm ccism
  • To specify that a particular CCI protocol is used when communicating with a specific Fileshare Server, use the /cm and /s options together:
    /cm ccism /s server1
    This tells the Fileshare Client to use CCISM for communicating with the Fileshare Server named server1.
  • To make the Fileshare Client use the TCP/IP protocol (CCITCP) as the default and CCISM for communicating with server1:
    /cm ccitcp
/cm ccism /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
About CCISMEM
Using CCISMEM
Logging Fileshare Messages: 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 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 Configuring the CCI Timeout 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 re-attempt 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 every data file you want assigned to a specific custom 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
/um
 Micro Focus Common Client (MFCC) shall be used to communicate with the Fileshare server/listener. MFCC can be configured using a mf-client.dat configuration file to automatically connect to servers on remote machines.
/ra
 The number of times a client will attempt to reconnect to a Fileshare server if its connection is lost. The default is 0. In a high availability environment fhredir will connect to a new fileshare listener if one becomes available.
/rd
 The length of time (in milliseconds) a client will wait between each re-connection attempt (specified by /ra). The default is 0.

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.
/fc
 Enables flush on commit, which flushes the cached file operations to disk after every COMMIT statement. Use this option in conjunction with /lw if you want to use advanced rollback recovery in the event of a device or operating system failure.
Note: Setting this option will degrade the performance of Fileshare.
/lw
 Enables write through, so that file operations are written to the cache and disk at the same time. Use this option in conjunction with /fc if you want to use advanced rollback recovery in the event of a device or operating system failure.
Note: Setting this option will degrade the performance of Fileshare.
  • 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


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
  • About CCISMEM
  • Using CCISMEM
  • Logging Fileshare Messages: 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
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
About CCISMEM
Using CCISMEM
Logging Fileshare Messages: 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
About CCISMEM
Using CCISMEM
Logging Fileshare Messages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout
Configuring CCI


About CCISMEM

CCISMEM (ccism) uses a Named Shared Memory communications method to transfer date between two processes on the same Windows system. Both the client and the server application must reside on the same Windows system.

These shared memory transfers are typically about as fast as its possible to transfer data buffers between processes. Individual data transfers that fit within the shared memory segment are typically several context switches faster than using TCP/IP in loopback mode to move the same data. As buffer sizes grow the difference becomes less noticeable, but is still present. By default, shared memory segments are 8K in size, but this is easily configurable using the cci.ini configuration file options.

When using Fileshare with the CCISM protocol, ensure the server is started using the /sc switch. This switch starts Fileshare in synchronous communications mode, which gives the best performance.

To also use clients located on other systems, you must configure Fileshare Server to use CCITCP as well as CCISM. To do this, in cci.ini, set the following configuration options:

-cm ccitcp -cm ccism

Using two protocols within a single Fileshare Server prevents Fileshare Server being used in synchronous mode; this is the only functionality that is lost with this type of configuration.

From a client perspective, the default CCITCP functionality doesn't require much FHREDIR.CFG configuration. When using CCISMEM you will need to use the following client options:

/cm ccism
Note: When using CCISMEM, the /MA parameter should not normally be used as it has a different meaning in the context of Named Shared Memory. The /MA option is equivalent to using the mem_files_location option in the cci.ini configuration file.
Parent topic: Configuring CCI Communications for Fileshare
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
Using CCISMEM
Logging Fileshare Messages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Using CCISMEM

Fileshare defaults to using the TCP/IP (CCITCP) protocol. If you are running both the Fileshare server and the Fileshare client on the same Windows system you can use an alternative connection protocol that utilises shared memory: CCISM.

Shared Memory transfers are usually faster than using TCP/IP between two processes.

To configure a Fileshare server to use the CCISM protocol, use the following option:

fs -cm ccism

To give the best performance, we also recommend that you start the Fileshare server with the /sc option (synchronous communications mode).

You can combined multiple communications methods for the Fileshare server, as follows:

fs -cm ccism –cm ccitcp

Unfortunately, you cannot run multiple protocols on a Fileshare server that is running in synchronous mode.

To configure a Fileshare client to use CCISMEM, you must use the following line in your FHREDIR.CFG configuration file:

/CM ccism
Note: When using CCISMEM, the /MA parameter in FHREDIR.CFG has no effect.

Many configuration options exist for CCISMEM, 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 CCITCP
About CCISMEM
Logging Fileshare Messages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Logging Fileshare Messages: 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.

CCI Trace is enabled through the Consolidated Tracing Facility (CTF); additionally, to trace CCI activity through the Fileshare Server, 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
About CCISMEM
Using CCISMEM
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
About CCISMEM
Using CCISMEM
Logging Fileshare Messages: 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
About CCISMEM
Using CCISMEM
Logging Fileshare Messages: CCI Trace
Using Multiple Protocols with Test Programs


Database Integrity

This chapter describes all of those Fileshare features which enable you to safeguard the integrity of your database:
  • 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.
  • Recovery Logging
    Logging the actions performed within Fileshare helps you to recover data in the event of a system failure.
  • Fileshare Recovery
    The Fileshare Recovery Utility enables you to recover updates to data files after a system failure.
  • 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.
  • Database Backup and Recovery
    To alleviate data loss and optimize recovery time, ensure you back up your Fileshare database regularly.
  • Database Reference File Maintenance
    The database reference file contains references to data files and the actions that Fileshare Server performs on them.
  • Best Practices for Backup and Recovery
    Use these best practices to optimize the backup and recovery processes within Fileshare.
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Security
Advanced Operation
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
Recovery Logging
Fileshare Recovery
Database Sequence Numbering
Database Backup and Recovery
Database Reference File Maintenance
Best Practices for Backup and Recovery
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

Normally, you do not need to change the configuration of the Fileshare Server to enable transaction processing. However, if you are using IDXFORMAT 17 and 21 files, transaction processing is not supported by default; you must configure it on a file-by-file basis using the Virtual File Handler option (/ap) when specifying the file in your database reference file. For example, when you access the following file through Fileshare, it is additionally re-directed to the ACUFH file handler, where transactional support can be provided:
Fs /d dbase.ref /f acufile1.dat /ap ACUFH

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


Recovery Logging

Logging the actions performed within Fileshare helps you to recover data in the event of a system failure.

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

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 log file(s) are used by a recovery utility to re-apply the updates to the 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).

There are two versions of recover logging that you can use. A basic version of logging, which is enabled as default, provides a Rollforward Recovery Utility. An advanced version of logging, which you must enable, provides Rollforward and Rollback Recovery. The advanced logging version also has other benefits that the basic version does not, such as compatibility with a user exit procedure and with hot backups.

You can only use one version of logging at any one time.

You do not need to make any changes to the Fileshare Client in order to use recovery logging.

  • Basic Recovery Logging
  • Advanced Recovery Logging
Parent topic: Database Integrity
Related information
Transaction Processing
Fileshare Recovery
Database Sequence Numbering
Database Backup and Recovery
Database Reference File Maintenance
Best Practices for Backup and Recovery


Basic Recovery Logging

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 Database Reference File Maintenance 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 Basic 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 that are referenced 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 it. 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 Basic Rollforward Recovery Utility implicitly rolls back the transaction when the files are recovered.

Parent topic: Recovery Logging
Related concepts
Advanced Recovery Logging


Advanced Recovery Logging

When advanced recovery logging is enabled, you have more control over how you back up and recover your data files.

There are two types of recovery available when you have enabled advanced recovery logging:

Rollback recovery
A fast recovery method suited to application failures. In the event of system failures, you can only use this if you have enabled additional logging features, which do have an effect on day-to-day Fileshare performance.
Rollforward recovery
A recovery method suitable for all types of failure, and does not require the additional flushing features.

Advanced recovery logging can be configured to use only the rollback method, or to use both methods.

With advanced recovery logging enabled, you can have more control over recovery by using a user exit procedure (fsexitproc.cbl), and you are able to view the log file in a user-readable format.

Advanced logging also enables you to take more regular backups, using the hot backups option, which doesn't require you to shut down Fileshare.

The Database sequence numbering, and automatic backup and recovery options are not available when advanced logging is enabled.

  • Enabling Advanced Recovery Logging
  • Fileshare Exit Procedure - fsexitproc.cbl
  • Viewing the Log Files
Parent topic: Recovery Logging
Related information
Basic Recovery Logging


Enabling Advanced Recovery Logging

Advanced recovery logging can be enabled either for rollback recovery only, or for rollback and rollforward recovery, by entering one of the following commands on the Fileshare server:

To enable logging for rollback recovery only:

FS /d dbase.ref /ltf logtrans.dat

To enable logging for both types of recovery:

FS /d dbase.ref /ltf logtrans.dat /ltt f
where:
Syntax | Explanation
/d dbase.ref | Specifies the database reference file
/ltf logtrans.dat | Specifies the log file for advanced logging
/ltt f | Specifies logging compatible with rollforward recovery, as well as rollback recovery

If you want to use rollback recovery for system failures, you need to enable extra logging, which has an impact on performance. You must have enabled the write through (/lw) and flush on commit (/fc) options when Fileshare was started, either on the command line, or by setting them in the fs.cfg file. You do not need to enable these settings if you plan to use only rollforward recovery.

Parent topic: Advanced Recovery Logging


Fileshare Exit Procedure - fsexitproc.cbl

When you have advanced recovery logging enabled, you can use the exit procedure fsexitproc.cbl to programmatically control logging, recovery and backup behavior.

The exit procedure is located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib.

To use the exit procedure, you must compile it, then deploy it to the Fileshare working directory. The procedure is fully annotated with details on how you can use it, and some examples of its use are given in Best Practices for Advanced Logging.

Parent topic: Advanced Recovery Logging


Viewing the Log Files

At a command prompt, enter the following command to view a log file that has been used for advanced recovery logging (.tlog)

cobfhtlog filename
where filename is the path to a .tlog file.
Parent topic: Advanced Recovery Logging


Fileshare Recovery

The Fileshare Recovery Utility enables you to recover updates to data files after a system failure.
Note: The Fileshare Recovery Utility can only be used to recover a database if the updates were logged to a recovery log file. See the section Recovery Logging for further details.
  • Basic Rollforward Recovery
    The rollforward recovery process to run when you have basic recovery logging enabled.
  • Advanced Rollforward Recovery
    The rollforward recover process to run when you have advanced recovery logging enabled.
  • Advanced Rollback Recovery
    The rollback recover process to run when you have advanced logging enabled.
Parent topic: Database Integrity
Related information
Transaction Processing
Recovery Logging
Database Sequence Numbering
Database Backup and Recovery
Database Reference File Maintenance
Best Practices for Backup and Recovery


Basic Rollforward Recovery

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 backed 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: Fileshare Recovery
Related information
Advanced Rollforward Recovery
Advanced Rollback Recovery


Advanced Rollforward Recovery

Advanced rollforward recovery is available if you have advanced logging enabled using the /ltt f parameter.

You can use this process to recover from all types of failure.

Unlike the rollback recovery process, it does not require the extra flushing process in the event of operating system, device or power failure.

To recover the data files, replace them with the current backup files, and then forward recover those files. The time this takes depends on how regular you take a backup; see the Best Practices section for the best way to set up Fileshare recovery.

If you use the user exit procedure (fsexitproc.cbl), you can control which files are recovered using this process.

To run the advanced rollforward recovery process:

fs /r dbase.ref

When recovery is complete, you should archive the existing log files; otherwise you receive the following error when Fileshare is next started:

FS302-S Unable to continue - A log file already exists.

Parent topic: Fileshare Recovery
Related information
Basic Rollforward Recovery
Advanced Rollback Recovery


Advanced Rollback Recovery

Advanced Rollback Recovery is available if you have advanced logging enabled.

In most circumstances, Rollback Recovery is a faster process (than rollforward) to recover data files. Rollback Recovery attempts to recover the data files at the point of the Fileshare failure.

However, in situations where a system failure has occurred in which the cache has not been flushed to disk, Rollback Recovery will not work unless extra logging is enabled.

The extra logging involves enabling the write through (/lw) and flush on commit (/fc) options when Fileshare was started, either on the command line, or by setting them in the fs.cfg file. These two options do come at cost to performance though, as data is written to both the cache and to disk for a single operation.

During recovery from a system failure, or if a data file was in the process of updating their index when Fileshare failed, a data scrape may be required, which if the data file is large, can be time consuming.

If a data scrape is required, the default action is to run it, but you can use fsexitproc.cbl to prevent large files from running a data scrape. Use the 78-file-recovery-rbld-strt clause to interrogate the size of the file (offset-x) and make the decision to perform the data scrape or skip to the next file. You must make a note of any files that are skipped, then perform rollforward recovery on those files.

See the Best Practices Advanced Logging section for the best way to set up Fileshare recovery.

To initiate the advanced Rollback Recovery process:

fs /rb dbase.ref

When recovery is complete, you should archive the existing log files; otherwise you receive the following error when Fileshare is next started:

FS302-S Unable to continue - A log file already exists.

Parent topic: Fileshare Recovery
Related information
Basic Rollforward Recovery
Advanced Rollforward Recovery


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.
Note: Database sequence numbering is not supported if you have advanced logging enabled.

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 basic rollforward recovery 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 Fileshare Recovery 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
Recovery Logging
Fileshare Recovery
Database Backup and Recovery
Database Reference File Maintenance
Best Practices for Backup and Recovery


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


Database Backup and Recovery

To alleviate data loss and optimize recovery time, ensure you back up your Fileshare database regularly.
  • Automatic Database Backup and Rollforward Recovery
    When basic logging is enabled, you can set Fileshare to back up and, if required, perform rollforward recovery each time Fileshare is started.
  • Hot Backups
    Hot backups enable you to take a backup of your database files and start a new log file without the need to shutdown and restart the Fileshare Server.
Parent topic: Database Integrity
Related information
Transaction Processing
Recovery Logging
Fileshare Recovery
Database Sequence Numbering
Database Reference File Maintenance
Best Practices for Backup and Recovery


Automatic Database Backup and Rollforward Recovery

When basic logging is enabled, you can set Fileshare to back up and, if required, perform rollforward recovery each time Fileshare is started.
Note: Automatic database backup and recovery is not supported if you have advanced logging enabled.

The recommended method of using Fileshare's basic recovery logging for rollforward recovery is:

  1. Periodically 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 Basic Recovery Logging for further details.

Fileshare can perform these actions automatically if you specify a backup directory-name in the database reference file using the /backup option. For example, the command:

fs /d dbase.ref /backup	c:\backdir

adds an entry to the database reference file called dbase.ref which specifies the backup directory as c:\backdir. 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 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 successfully, 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

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

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 are logged
  • Specify c:\backdir as the backup directory

On startup, the Fileshare Server automatically backs up these data files in the directory c:\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 are restored to their original directories and any updates recorded in the log file(s) are re-applied.

Parent topic: Database Backup and Recovery


Hot Backups

Hot backups enable you to take a backup of your database files and start a new log file without the need to shutdown and restart the Fileshare Server.
Note: Hot backups are only available if you have advanced logging enabled.

You can run a hot backup if the Fileshare server resides on an operating system that supports a snapshot process; for example, DiskShadow, which is shipped with modern Windows platforms.

To run a hot backup, you need to:
  • Enable advanced logging for rollforward recovery
  • Be able to run commands in supervisor mode in FSVIEW.
  • Configure the exit procedure (fsexitproc.cbl) to call the snapshot utility

When a hot backup is initiated, Fileshare suspends the start of new transactions, putting these into a hold state until all outstanding requests are processed. When they are complete, control is handed to fsexitproc.cbl, where you can code a command line invocation to your snapshot utility, to back up your data files.

When the snapshot is complete, normal transaction processing resumes.

Note: During the period where the outstanding transactions have been finalized and new transactions are resumed, the server does not communicate with its clients. If this duration is longer than a client CCI-Timeout setting, the client will disconnect from the server; therefore, you may need to increase the setting in a Fileshare Client configuration file to ensure that it does not disconnect while the hot backup is running.

  • Running a Hot Backup
Parent topic: Database Backup and Recovery


Running a Hot Backup

Note: Hot backups are only available if you have advanced logging enabled.
  1. At the command prompt, type FSVIEW.

    The FSVIEW Administration Utility is started.

  2. To log on to supervisor mode, type admin logon <username> <password>, where <username> and <password> are your Fileshare logon credentials.
  3. To log on to the server, type server set <server-name>, where <server-name> is the name of the Fileshare server.
  4. Type backup init.

    Fileshare now only processes file operations for in-flight transactions. While these transactions are being processed, you can enter backup cancel at the FSVIEW prompt to cancel the backup.

  5. When all sessions have been processed, control is passed to the 78-transactions-newlog clause in fsexitproc.cbl.

    when 78-transactions-newlog
    *> Fileshare is ready to create a new log.
     *> used when roll forward logging is enabled.
     *> default it to start new log
     *> set action to determine what occurs..
     *> don't start new log     value h"0000".
     *> start new log           value h"0001".
continue
    At this point, the log file is finalized, the data files are flushed to disk, and if the default action is set, a new log file is created.
    Note: Any new requests are cycled until the backup has completed; ensure Fileshare clients do not time out during this period by setting CCI TIMEOUT to a sufficient period of time; see Best Practices for Advanced Logging for more details.
  6. When the files are ready, control then moves to the 78-transactions-suspended clause in fsexitproc.cbl.
    Note: fsexitproc.cbl contains an example of how the backup can be taken using the Diskshadow utility (see below) and a script file example. Update this clause to run your preferred utility.
    when 78-transactions-suspended
   call "CBL_EXEC_RUN_UNIT"
      using "diskshadow.exe /s script.dsh "
                       by value  52
                       by reference runit-run-id
                       by value     runit-stack-sz
                                    runit-flags
                returning return-code
   continue
    The accompanying script file example
    *> Example script.dsh for use with diskshadow.exe (Windows)
#DiskShadow script file
set context persistent nowriters
set metadata c:\diskshadowdata\example.cab
set verbose on
begin backup
add volume d: alias SystemVolumeShadow

create
unexpose p:
expose %SystemVolumeShadow% p:
end backup
*> #End of script

    When the snapshot has been taken, Fileshare resumes normal transaction processing.

  7. You should now copy the data files from the snapshot to a safe location.
Parent topic: Hot Backups


Database Reference File Maintenance

The database reference file contains references to data files and the actions that Fileshare Server performs on them.

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.

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.

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 filenaming conventions.

Invoke the Database Reference File Maintenance Utility 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
Recovery Logging
Fileshare Recovery
Database Sequence Numbering
Database Backup and Recovery
Best Practices for Backup and Recovery


Recovery Log File Records

You specify the name of the recovery log file using the /l option (basic logging) or /ltf (advanced logging), for example:

Basic logging:

fs /d dbase.ref /l logfilename

Advanced logging:

fs /d dbase.ref /ltf logtrans.dat

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) (basic logging only)
  • 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

Note: This option is not supported if you have advanced logging enabled.

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


Best Practices for Backup and Recovery

We recommend that you use the following guidelines optimize the recovery and backup processes. By optimizing the processes, the time taken to recover files will be shorter.

  • Best Practices Basic Logging
  • Best Practices Advanced Logging
Parent topic: Database Integrity
Related information
Transaction Processing
Recovery Logging
Fileshare Recovery
Database Sequence Numbering
Database Backup and Recovery
Database Reference File Maintenance


Best Practices Basic Logging

The recommended method of using basic recovery logging is:

  1. Optimize your log file activity.

    Basic recovery logging can severely affect performance. To optimize logging activity, you can use the /o l option in the database reference file to switch logging off for files that do not need to be recovered in the event of a failure. Alternatively, use the /e option to remove such files from the database reference file altogether.

  2. Set low disk space warnings.

    If you have a large number of updates being logged, the log file can grow very large, very quickly. If the disk where the log file resides were to become full, the ability to write records to the log file could be lost, resulting in an incomplete log file, forcing the Fileshare Server to close down. Use the /p option in the database reference file to configure a warning to be displayed when the amount of free disk space for the log file drops below a certain percentage of the total disk. If 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.

  3. Take regular backups.

    Regular backups (preferably daily) keep the size of the log files as small as possible; larger log files means that recover time is longer.

  4. Automate the backup process.

    Use the /backup option to automate backing up of the data files and stating a new log file when you start Fileshare Server.

  5. Delete redundant log files.

    Once you have backed up your data files, delete any associated log files, because they are now obsolete; you only need to log updates since your last backup.

Parent topic: Best Practices for Backup and Recovery


Best Practices Advanced Logging

When advanced logging is enabled, use these recommendations for backup and recovery processes on your data files.

  1. Enable advanced recovery logging for both rollforward and rollback recovery.

    Advanced recovery logging provides a more flexible solution that basic logging when recovery is required.

    fs /d dbase.ref /ltf <filename>.tlog /ltt f
  2. Only enable logging for essential files.

    You can disable logging for non-essential files by appending the following option to the command above:

    /f filename /o l

  3. Take regular backups.

    Run a backup on (at least) a daily basis, which will start a new log file after each backup. Keeping the size of your log files relatively small will ensure that rollforward recovery will take less time to run.

  4. Optimize hot backup times.

    When taking a snapshot of the data files, the snapshot will be quicker if the data files being logged are stored on their own volume.

  5. Where possible, use rollback recovery as your default recovery method.

    Rollback recovery is quicker than rollforward recovery, but under certain circumstances, it may take longer (such as when a data scrape is required).

    If a data scrape is required, the default action is to run it, but you can use fsexitproc.cbl to prevent large files from running a data scrape. Use the 78-file-recovery-rbld-strt clause to interrogate the size of the file (offset-x) and make the decision to perform the data scrape or skip to the next file. You must make a note of any files that are skipped, then perform rollforward recovery on those files.

  6. When not to attempt the rollback recovery process.

    Do not attempt rollback recovery if a system failure occurred and the cache failed to write to disk, unless you started Fileshare with the /lw (write through) and /fc (flush on commit) options; you can add these options to the Fileshare Server configuration file, but they will affect performance. If these options are not set, use rollforward recovery instead.

  7. Only recover the necessary files.

    After a rollback recovery, if some files were skipped and require rollforward recovery, you can use the 78-file-recovery clause in fsexitproc.cbl to again skip over non-essential files.

Parent topic: Best Practices for Backup and Recovery


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
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 LIBPATH on AIX 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:

  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:

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.

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:

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.

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
  • Running Fileshare as a Windows Service
  • Performance Considerations
  • Large File Support with Fileshare
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
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
Running Fileshare as a Windows Service
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
Running Fileshare as a Windows Service
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
Running Fileshare as a Windows Service
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 using Fileshare, IDXFORMATs 17 and 21 do not provide transaction processing capabilities by default. You must configure it on a file-by-file basis using the Virtual File Handler option (/ap) when specifying the file in your database reference file. For example, when you access the following file through Fileshare, it is additionally re-directed to the ACUFH file handler, where transactional support can be provided:
Fs /d dbase.ref /f acufile1.dat /ap ACUFH

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
Running Fileshare as a Windows Service
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:

On Windows, your program should be compiled to intermediate or generated code, or to a dynamic link library, and must be callable from the Fileshare process.

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
Running Fileshare as a Windows Service
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
Running Fileshare as a Windows Service
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
Running Fileshare as a Windows Service
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
Running Fileshare as a Windows Service
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


Running Fileshare as a Windows Service

You can use the Fileshare Server so that it runs as a Windows service, using the following commands:

fsservice -i [service-name [configuration-options] ]
fsservice -u [service-name]
fsservice -v [service-name]

Where:

-i
Install the service.
-v
Display the status of the service.
-u
Uninstall the service.
service-name
A unique name for the service. The service is called "Micro Focus Fileshare Service:name", where :name is included only if a name is specified. service-name is optional unless you specify configuration-options, in which case it is mandatory.
configuration-options
Options used to start the Fileshare service. See Fileshare Server Configuration .

To start the Fileshare service as a background process and to stop it:

  1. Make sure the License Manager service is started.
  2. Click Control Panel > Services.
  3. Select Micro Focus Fileshare Service[: service-name] from the list of displayed services.
  4. Click Start or Stop as appropriate.

    You can also choose to start the service automatically whenever Windows starts.

Notes:
  • When you stop the service from the Services window, as above, Fileshare closes down as normal. Any connected Fileshare clients are logged off and their data files closed (with any incomplete transactions rolled back).
  • When you shut down Windows, Fileshare is similarly shut down.
  • If you choose it to start the service automatically and you have logging switched on for any data files, we recommend that you specify a Fileshare backup directory in your database reference file.

For example, the following command installs a service called "Micro Focus Fileshare Service: My Service", which will execute in the c:\mydir directory and use a Fileshare server name of myserver:

fsservice -i "My Service" /wd c:\mydir /s myserver
  • Fileshare Server 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


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: Running Fileshare as a Windows Service


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:

  • Synchronous communications

    Where possible, you should use Fileshare in synchronous communications mode (/sc). This has been shown to improve performance significantly when using the CCISM protocol. We recommend that asynchronous mode (that is, Fileshare without the /sc setting) should be considered as being for development purposes only; production installations should always use synchronous mode, if possible.

    Note: Synchronous mode is only possible if all clients are using the same protocol to communicate with the Fileshare server.
  • 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.

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
Running Fileshare as a Windows Service
Large File Support with Fileshare


Fileshare Performance on UNIX

Fileshare improves performance when remote COBOL applications are concurrently accessing shared data files across a network but it cannot improve performance 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
Running Fileshare as a Windows Service
Performance Considerations


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
  • Fileshare Extended Status Codes
  • 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 Server Messages
Fileshare Server Messages


Fileshare Extended Status Codes

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
Fileshare Extended Status Codes
Transaction Processing Errors
Monitoring Fileshare
Configuring CCI


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
Fileshare Extended Status Codes
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 to FS300
  • Messages from FS301 - FS400
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
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 to FS300
Messages from FS301 - FS400


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 to FS300
Messages from FS301 - FS400


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 to FS300
Messages from FS301 - FS400


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 to FS300
Messages from FS301 - FS400


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 to FS300

  • 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
Messages from FS301 - FS400


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 to FS300
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 to FS300


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 to FS300
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 to FS300


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 to FS300


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 to FS300
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 to FS300


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 to FS300


FS209-I A starter log file has been located in the backup directory.

Resolution:

No action is required.

Parent topic: Messages from FS201 to FS300


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 to FS300
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 to FS300


FS212-I The Rollforward Recovery Utility is processing the log file "filename".

Resolution:

No action is required.

Parent topic: Messages from FS201 to FS300


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 to FS300


FS214-I Searching for a backed up log file in the log file directory.

Resolution:

No action is required.

Parent topic: Messages from FS201 to FS300


FS215-I Searching for a backed up log file in the backup directory.

Resolution:

No action is required.

Parent topic: Messages from FS201 to FS300


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 to FS300


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 to FS300


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 to FS300


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 to FS300


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 to FS300


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 to FS300


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 to FS300


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 to FS300


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 to FS300
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 to FS300
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 to FS300


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 to FS300
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 to FS300


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 to FS300


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 to FS300


FS232-I Date : date.

Resolution:

No action is required.

Parent topic: Messages from FS201 to FS300


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 a Fileshare NLM failure. Please contact our technical support department.

Parent topic: Messages from FS201 to FS300


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 to FS300


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 to FS300
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 to FS300


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 to FS300


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 to FS300


FS238-I Terminating communications with this user.

Resolution:

No action is required.

Parent topic: Messages from FS201 to FS300
Related information
FS015-W


FS239-I Output - user Record locked. Retry operation.

Resolution:

No action is required.

Parent topic: Messages from FS201 to FS300


FS240-I Output - user File locked. Retry operation.

Resolution:

No action is required.

Parent topic: Messages from FS201 to FS300


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 to FS300
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 to FS300


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 to FS300


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 to FS300


FS246-I Backing up database files to directory backup directory. Please wait.

Resolution:

No action is required.

Parent topic: Messages from FS201 to FS300


FS247-I Restoring database files from directory backup directory. Please wait.

Resolution:

No action is required.

Parent topic: Messages from FS201 to FS300


FS248-I Commencing automatic Fileshare Recovery.

Resolution:

No action is required.

Parent topic: Messages from FS201 to FS300


FS249-I Restarting Fileshare Server.

Resolution:

No action is required.

Parent topic: Messages from FS201 to FS300


FS250-I Deleting all unwanted log files.

Resolution:

No action is required.

Parent topic: Messages from FS201 to FS300


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 to FS300


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 to FS300


Messages from FS301 - FS400

  • FS302-S Unable to continue - A log file already exists
    Fileshare is unable to start, because a previous log file exists.
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
Messages from FS201 to FS300


FS302-S Unable to continue - A log file already exists

Fileshare is unable to start, because a previous log file exists.

Resolution

You need to delete or archive the existing log files, then restart logging with new files when you start Fileshare again.

Parent topic: Messages from FS301 - FS400


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.
Parent topic: Micro Focus Enterprise Server 2.3 Update 1 for Windows


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.
  • 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
  • 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:
    set MFTRACE_CONFIG=c:\ctf\ctf.cfg
  2. Set the MFTRACE_LOGS environment variable to specify the location in which to create the CTF trace files. If MFTRACE_LOGS is not set, the current folder is used.
    Note: Both the 32- and 64-bit Enterprise Developer command prompts set MFTRACE_LOGS to %ProgramData%\Micro Focus\Enterprise Developer\2.x\mftrace\logs.
  3. Edit the configuration file to specify the information to trace, for example:
    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
    Note: If the location of the trace 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 the .NET environment, instead of setting the MFTRACE_CONFIG variable you can configure CTF tracing in an app.config file in the same folder as its associated app.exe file. The configuration statements must be inserted in an <mftrace_config> section in the <configSections> as CDATA. For example:

<?xml version ="1.0"?>
  <configuration>
    <configSections>
      <sectionGroup name="MicroFocus.COBOL.Tracing">
        <section name="mftrace_config"
         type="MicroFocus.COBOL.Runtime.CdataSectionHandler,
         MicroFocus.COBOL.Runtime.Win32,Version=4.0.0.0,Culture=neutral,
         PublicKeyToken=0412c5e0b2aaa8f0" />
      </sectionGroup>
    </configSections>
    <MicroFocus.COBOL.Tracing>
      <mftrace_config>
        <![CDATA[>
mftrace.dest                           = binfile
mftrace.emitter.binfile#location       = c:\logs
mftrace.level.mf.rts                   = info
mftrace.comp.mf.rts#pgm                = true
mftrace.comp.mf.rts#pgmload            = true
mftrace.comp.mf.rts#syspgm             = true
        <]]>
      </mftrace_config>
    </MicroFocus.COBOL.Tracing>
  </configuration>
Note: If the MFTRACE_CONFIG variable is set, CTF uses it in preference to an app.config file.

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 Team Developer Tree view, right-click the project name, then click New > Folder > Folder.

    The New Folder dialog box 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.
Parent topic: The Consolidated Tracing Facility
Related information
Example CTF Configuration Files
TEXTFILE Emitter Properties
BINFILE Emitter Properties


Components Traced by CTF

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

  • mf.cci Properties
    This component provides CCI activity.
  • mf.esmq Properties
    This component provides calls to the WebSphere MQ XA switch module.
  • mf.esxa Properties
    This component provides diagnostics on the various SQL operations invoked by the switch modules when executing SQL applications that have been deployed under Enterprise Server.
  • 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.mvs.casspool Properties
    This component provides JCL workload management, such as job submission, dispatch, printing and held SYSOUT.
  • mf.mvs.mvscatio Properties
    This component supports the JES system catalog, which maintains the relationship between the native file system and the MVS/VSE form of data set names.
  • mf.mvs.mfjcl Properties
    This component provides the main JCL processing functionality.
  • mf.rts Properties
    This component provides behavior of the run-time system.
  • mf.mvs.le37 Properties
    This component provides language environment services support.
Parent topic: The Consolidated Tracing Facility


mf.cci Properties

This component traces CCI function calls made by applications. As well as setting the following in the ctf.cfg file:

mftrace.comp.mf.cci = info

You must also set the CCITRACE environment variable or edit the [ccitrace_base] section of cci.ini, and it is the value given in the variable or cci.ini that determines the degree of information traced.

Parent topic: Components Traced by CTF
Related information
CCITRACE Environment Variable
Tracing Options for cci.ini


mf.esmq Properties

This component provides calls to the WebSphere MQ XA switch module.

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

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


mf.esxa Properties

This component provides diagnostics on the various SQL operations invoked by the switch modules when executing SQL applications that have been deployed under Enterprise Server.

The following table lists the properties of the mf.esxa component, and shows the event information that can be included in the trace for each property. Although you can create your own trace files, Micro Focus recommends that you use the configuration files supplied with the switch module source files as the basis for tracing. Note that when setting the trace options, the only item that needs to be enabled is mftrace.level.mf.esxa. That is, the sub-properties are not used for tracing this component.

ESMSSQL
Event Level | Event ID | Event Description
INFO | 1 | Initialization of module
ERROR | 2 | Incorrect XA Open String provided
INFO | 3 | SQL CONNECT
INFO | 4 | Microsoft Distributed Transaction Coordinator (DTC) initialization
INFO | 5 | Begin DTC Transaction
INFO | 6 | Enlist in DTC Transaction
INFO | 7 | DTC Commit
INFO | 8 | DTC Rollback
INFO | 9 | SQL DISCONNECT
INFO | 10 | End DTC Transaction
ESODBCXA
Event Level | Event ID | Event Description
INFO | 21 | BEGIN TRANSACTION
INFO | 22 | SQL COMMIT
INFO | 23 | SQL ROLLBACK
INFO | 24 | SQL DISCONNECT
INFO | 26 | Initialization of module
ERROR | 27 | Incorrect XA Open String
INFO | 28 | SQL CONNECT
INFO | 29 | SQL SYNCPOINT
INFO | 30 | SQL RESET CONNECTION
ESDB2XA
Event Level | Event ID | Event Description
INFO | 41 | xa_start()
INFO | 42 | xa_end()
INFO | 43 | xa_open() - database connection
INFO | 44 | xa_close()
INFO | 45 | xa_commit()
INFO | 46 | xa_rollback()
INFO | 47 | xa_prepare()
INFO | 48 | Call to IBM DB2 LUW XA initialization
ESDB2OPC
Event Level | Event ID | Event Description
ERROR | 61 | Incorrect XA Open String
INFO | 62 | SQL CONNECT
INFO | 63 | SQL COMMIT
INFO | 64 | SQL ROLLBACK
INFO | 65 | SQL DISCONNECT
INFO | 66 | Before SQL CONNECT
INFO | 67 | Before SQL COMMIT
INFO | 68 | Before SQL ROLLBACK
INFO | 69 | Before SQL DISCONNECT
ESORAXA
Event Level | Event ID | Event Description
INFO | 81 | xa_start()
INFO | 82 | xa_end()
INFO | 83 | xa_open() - database connection
INFO | 84 | xa_close()
INFO | 85 | xa_commit()
INFO | 86 | xa_rollback()
INFO | 87 | xa_prepare()
INFO | 88 | Load of Enterprise Server callback module
INFO | 89 | Load of Oracle client-side support
INFO | 90 | Call to Oracle XA initialization entry point
ESORAOPC
Event Level | Event ID | Event Description
ERROR | 101 | Incorrect XA Open String
INFO | 102 | SQL CONNECT
INFO | 103 | SQL COMMIT
INFO | 104 | SQL ROLLBACK
INFO | 105 | SQL DISCONNECT
INFO | 106 | Before SQL CONNECT
INFO | 107 | Before SQL COMMIT
INFO | 108 | Before SQL ROLLBACK
INFO | 109 | Before SQL DISCONNECT
Parent topic: Components Traced by CTF


mf.mffh.fs Properties

This component provides Fileshare processing.

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

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


mf.mffh.xfh Properties

This component provides the Micro Focus File Handler system.

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

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


mf.mffh.xsm Properties

This component provides the Micro Focus Sort module.

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

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

Parent topic: Components Traced by CTF


mf.mvs.casspool Properties

This component provides JCL workload management, such as job submission, dispatch, printing and held SYSOUT.

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

Property | Property Description | Level | Event Id | Event Description
ACTIVE | Movement of a job into active status. The job is given to the batch initiator for execution and upon completion of the job the batch initiator signals that it is ready for more work. | DEBUG | 4 | Compiled JCL has been executed.
COMP | Submission of JCL by Enterprise Server to be syntax checked. | DEBUG | 2 | A JCL file has been submitted for syntax scanning.
DELETE Removal of a job from the input, output, held, printing or active queues. DEBUG 7 A job has been removed from one of these quese. This could have occurred for the following reasons:
  • an active job has been killed
  • output has been requeued
  • a purge has taken place
DISP | Movement of a job from the input queue so that it can be executed by a batch initiator. | DEBUG | 3 | The next available compiled JCL for a given class and priority has been requested for scheduling in an available batch initiator.
OPEN | Opening and closing of the casspool.dat file. | DEBUG | 10 | casspool.dat is accessed when starting and stopping an initiator, initializing and terminating an enterprise server, and restarting a generic SEP.
OUTPUT | Movement of a job that has completed from the active queue to the output queue and performing of any associated cleanup tasks. | DEBUG | 5 | Compiled JCL has finished executing.
PRINT | Routing of a job to a batch printer or a batch printer exit. | DEBUG | 9 | This routing occurs upon job completion for active batch printers or when a SYSOUT is driven to the printer by requeuing.
REPL Replacement of a job that has either been made active or had been requested for execution into either the input or output queues. DEBUG 6 A job bas been replaced. This could have happened for the following reasons:
  • the job was previously active and canceled
  • a protection violation occurred in the batch initiator
  • a protection violation occurred in one of your programs
  • job was canceled by the operator

If the job was previously active it is moved to the output queue for review. If it was never made active then it is replaced in the input queue.

RETRIEVE | Requests to retrieve information about a job or SYSOUT DDs that are associated with a job. | DEBUG | 8 | These requests typically occur because of an interaction with ESMAC or when the casout utility needs to retrieve SYSOUT information.
Parent topic: Components Traced by CTF
Related information
Introduction to the Consolidated Tracing Facility
Components Traced by CTF


mf.mvs.mvscatio Properties

This component supports the JES system catalog, which maintains the relationship between the native file system and the MVS/VSE form of data set names.

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

Property | Property Description | Level | Event Id | Event Description
BUFFER | Buffer for MVSCATIO files. | DEBUG | 5 | The buffer used for MVSCATIO files in binary format. This is useful for subrecord tracing.
DELETE | Functions that occur when an MVSCATIO DLET function code is executed. | DEBUG | 3 | Unexpected failures, and information such as whether a file was able to be physically deleted or if alternate indexes were processed.
ENQUE | Enqueues on a record. | DEBUG | 3 | Data set records that are being locked and waited for.
ENTRY | Entry to or exit from MVSCATIO. | DEBUG | 3 | Primary key, file status, and return codes for a given call to MVSCATIO. This is very useful for diagnosing general problems with MVSCATIO.
MFALU | Mainframe Access lookups and their success or failure. | DEBUG | 3 | MVSCATIO calls that caused a Mainframe Access lookup to occur and whether or not the lookup was successful.
PHYS | Physical file name associated with a catalog entry. | DEBUG | 7 | The physical file name. This is useful in conjunction with the ENTRY property when trying to establish which physical files are associated with a given MVS name.
RECORDS | Catalog records. | DEBUG | 6 | The entire catalog record for a given I/O operation in binary form. This provides additional information that is not available when using the ENTRY property.
Parent topic: Components Traced by CTF
Related information
Introduction to the Consolidated Tracing Facility
Components Traced by CTF


mf.mvs.mfjcl Properties

This component provides the main JCL processing functionality.

The following table lists the property of the mf.mvs.mfjcl component and shows the event information that can be included in the trace for it.

Property | Property Description | Level | Event Id | Event Description
memstomp | Memory corruption event | ERROR | 79 | Memory has been corrupted.
Parent topic: Components Traced by CTF
Related information
Introduction to the Consolidated Tracing Facility
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
JSEM
This property is for native COBOL only. MVS Job Step Execution Manager events:
Event Level | Event Id | Event Description
INFO | 44 | JSEM function entry
INFO | 45 | JSEM function exit
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


mf.mvs.le37 Properties

This component provides language environment services support.

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

Property | Property Description | Level | Event Id | Event Description
ENTRY | Entry and exit to each program | DEBUG | 1 | Entry and exit to each program
 |  |  | 2 | Retrieve product and platform information
ENVIR | Environment Values | DEBUG | 3 | Report environment values that affect LE
SETPP | Setting procedure entry points | DEBUG | 4 | Report the setting of procedure entry points
CALL | Calling programs | DEBUG | 5 | Report the call to and response from a program
FILE | Reading configuration files | DEBUG | 6 | Report the actions and contents of LE configuration files
CGPIINFO | Call stack | DEBUG | 7 | Report program call stack
Parent topic: 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 run ), 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.

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  = 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

where:

  • c:\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.
  • IDEDBG Emitter Properties
    Set the IDEDBG emitter properties to output trace information to a debugger that is attached to a running process.
  • 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.
  • WINEVENT Emitter Properties
    Set the WINEVENT emitter properties to output trace information to the Windows log 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 "run".
$(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 run.exe executing as process-id 3456 and the MAXGENERATION property has not been specified, the trace file created will be called run.binfile.3456.ctb .
  • If the binfile emitter is being used to output trace events for myapp.exe 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.
Note: Both the 32- and 64-bit Enterprise Developer command prompts set MFTRACE_LOGS to %ProgramData%\Micro Focus\Enterprise Developer\2.x\mftrace\logs.

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


IDEDBG Emitter Properties

Set the IDEDBG emitter properties to output trace information to a debugger that is attached to a running process.

The IDEDBG emitter is provided to allow trace records to be output by a debugger, such as your COBOL development system, Visual Studio, or Eclipse at the point which they occur in the application being debugged.

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

mftrace.dest = IDEDBG

To use this emitter with your COBOL development system IDE, you must set the MFTRACE_CONFIG environment variable on the Environment Variables tab of the Configure IDE Environment dialog box. Trace events appear in the Debug messages tab when the application is debugged.

To use this emitter with a third-party debugger such as Visual Studio, you must set the MFTRACE_CONFIG environment variable in the environment before the debugger process is started. Trace events appear in the debugger‘s window where other system debug events would normally be displayed. For example, under Visual Studio 6, debug messages are displayed in the Debug tab.

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

Property | Description | Default
DELIMCHAR | The character used in the output file to delimit trace data parts for a trace event. | SPACE
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
$(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
LEVEL The trace level below which this emitter will not output trace records:
  • 0 = debug
  • 1 = info
  • 2 = warning
  • 3 = error
  • 4 = fatal
  • >4 = no trace records are output
3
QUOTESTRING | Whether or not string trace data is to be output enclosed in double-quote characters. . | TRUE
Parent topic: Emitter List


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 "run".
$(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 run.exe executing as process-id 3456 and the MAXGENERATION property has not been specified, the trace file created will be called run.textfile.3456.log .
  • If the TEXTFILE emitter is being used to output trace events for myapp.exe 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. On Windows platforms, the folder is specified by the MFTRACE_LOGS environment variable. If MFTRACE_LOGS is not set, the current folder is used.
Note: Both the 32- and 64-bit Enterprise Developer command prompts set MFTRACE_LOGS to %ProgramData%\Micro Focus\Enterprise Developer\2.x\mftrace\logs.

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


WINEVENT Emitter Properties

Set the WINEVENT emitter properties to output trace information to the Windows log file.

The WINEVENT emitter is provided to allow trace records to be output to the Windows event log. By default, to prevent the event log from being filled with unnecessary information, this emitter only outputs trace records with a trace level of error or above.

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

mftrace.dest = WINEVENT

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

Property | Description | Default
DELIMCHAR | The character used in the output file to delimit trace data parts for a trace event. | SPACE
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
$(THREAD)
The current operating system thread identifier.
$(TIME)
The current time, output as hh:mm:ss
$(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
LEVEL The trace level below which this emitter will not output trace records:
  • 0 = debug
  • 1 = info
  • 2 = warning
  • 3 = error
  • 4 = fatal
  • >4 = no trace records are output
3
QUOTESTRING | Whether or not string trace data is to be output enclosed in double-quote characters. . | TRUE
Parent topic: Emitter List


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:

set MFTRACE_CONFIG=e:\mydir\ctf.cfg

and e:\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        = 2404
4>   # Date             = 2004/12/14
5>   # Time             = 11:54:42.875
6>   # Operating System = Windows XP Service Pack 1 (Build 2600)
7>   # Computer Name    = PC-NAME
8>   # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
9>   11:54:42.875 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:54:42.875 | $(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        = 2820
    # Date             = 2004/12/14
    # Time             = 12:27:04.317
    # Operating System = Windows XP Service Pack 1 (Build 2600)
    # Computer Name    = PC-NAME
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    12:27:04.317 MF.RTS 128 1
    12:27:04.327 MF.RTS 129 1
    12:27:04.337 MF.RTS 255 3 173 1 "myprog"
    12:27:04.367 MF.RTS 130 1
    12:27:04.367 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        = 4092
    # Date             = 2004/12/14
    # Time             = 13:44:30.868
    # Operating System = Windows XP Service Pack 1 (Build 2600)
    # Computer Name    = PC-NAME
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    13:44:30.868 MF.RTS 128 1
    13:44:30.888 MF.RTS 129 1
    13:44:30.888 MF.RTS 19 1 0 0 "mymain" "" ""
    13:44:30.888 MF.RTS 6 1 17 0 "mymain"
    13:44:31.008 MF.RTS 19 1 0 0 "mysub" "gnt" "E:\myprogs"
    13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.008 MF.RTS 20 1 0 0 "mysub"
1>  13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.139 MF.RTS 255 3 173 1 "myprog"
    13:44:31.199 MF.RTS 130 1
    13:44:31.199 MF.RTS 20 1 0 0 "mymain"
2>  13:44:31.199 MF.RTS 6 1 17 0 "mymain"
    13:44:31.199 MF.RTS 7 1
    13:44:31.199 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        = 2716
    # Date             = 2004/12/14
    # Time             = 14:33:22.704
    # Operating System = Windows XP Service Pack 1 (Build 2600)
    # Computer Name    = PC-NAME
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    14:33:22.704 MF.RTS 128 1
    14:33:22.714 MF.RTS 129 1
    14:33:22.714 MF.RTS 19 1 0 0 "mymain" "" ""
    14:33:22.714 MF.RTS 6 1 17 0 "mymain"
1>  14:33:22.714 MF.RTS 26 1 "MY_VAR" 9
    14:33:22.714 MF.RTS 19 1 0 0 "mysub" "gnt" "E:\myprogs"
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 20 1 0 0 "mysub"
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 255 3 173 1 "myprog"
    14:33:22.764 MF.RTS 130 1
    14:33:22.764 MF.RTS 20 1 0 0 "mymain"
    14:33:22.764 MF.RTS 6 1 17 0 "mymain"
    14:33:22.764 MF.RTS 7 1
2>  14:33:22.764 MF.RTS 27 1 "MY_VAR"
    14:33:22.764 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

Micro Focus recommends that you use Profiler from within the IDE. See the links at the end of this topic for more information.

This section provides information about how to use the utility from the command line.

  • Introduction to Profiler
  • Running Profiler from the Command Line
  • Profiler Output
  • Time Spent in Called Programs
  • Directives for Profiler
Parent topic: Tools


Introduction to Profiler

Profiler is a facility that enables you to obtain detailed statistics on the run-time performance of a COBOL program.

When you compile a program 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=C:\myipfdir
Parent topic: Profiler


Running Profiler from the Command Line

To start Profiler from the Enterprise Developer command prompt, use the following command:

profiler 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.
Note: If you are profiling a .NET COBOL program, filenames must be in the format <assembly-name>.<program-name>.
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 ( \).

When you run Profiler, the following banner is displayed in the report:

* Micro Focus COBOL Profiler
* name-1
.
.
.
* name-n

where name is one of the files listed in filenames at the command line.

The following example shows the report, if you are using Profiler from the command line. If you compile the program prog1 with the PROFILE directive set, run the program, and then enter:

profiler prog1 +LIST

the following output is produced on the console:

* Micro Focus COBOL Profiler
* prog1
 Total time: 172 milliseconds. Module called once.

%time   time    entries  micros/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
Parent topic: Profiler


Profiler Output

When you run Profiler, the following banner is displayed in the report:

* Micro Focus COBOL Profiler
* name-1
.
.
.
* name-n

where name is one of the files in your project or one of the files listed in filenames, if you are running Profiler from the command line.

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

Note: Profiler reports can include unnamed paragraphs that appear if a program has sections or divisions without subsequent paragraphs, or in-line PERFORM and EVALUATE statements.
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 profiling enabled (a profiled program) depends on the value of the profile_behavior run-time tunable. You specify this tunable when you run the program or the application 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 to 1, 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 at the command line to control the behavior of the 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 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.
To write the output to a file, specify a destination which must be a path and a filename - for example, <path>\filename.txt or filename.txt.
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
Specifies whether Profiler messages are to be displayed on-screen. 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


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.
  • CCI Tracing
    You can trace CCI activity through the Consolidated Tracing Facility (CTF).
  • 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 Enterprise Server 2.3 Update 1 for Windows


CCITCP Configuration

  • CCI Support For TCP/IP
  • Advanced Features
  • Application Configuration
Parent topic: Configuring CCI
Related information
CCI Tracing
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 concepts
Using CCITCP2


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.

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 reference
Running the CCI Configuration Utility


Using Directory Server Instead of CCITCP2

If you have installed Enterprise Server, available with Enterprise Developer 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 Enterprise 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


CCI Tracing

You can trace CCI activity through the Consolidated Tracing Facility (CTF).
  • Enabling CCI Tracing
Parent topic: Configuring CCI
Related information
CCITCP Configuration
CCI.INI - The CCI Configuration File
CCI Status Messages
The Consolidated Tracing Facility


Enabling CCI Tracing

To enable CCI tracing, you must first enable CTF tracing, then edit the CTF configuration file, ctf.cfg, to trace the CCI component:

mftrace.comp.mf.cci = info

Once that has been set, you must then configure the degree of information traced using the CCITRACE environment variable or the [ccitrace_base] section of the cci.ini configuration file.

If you are also wanting to trace CCI information on a Fileshare server, you must activate tracing when the Fileshare server is started.

  • CCITRACE Environment Variable
  • Tracing Options for cci.ini
  • Activating CCI Tracing for Fileshare
Parent topic: CCI Tracing
Related information
To Enable CTF Tracing


CCITRACE Environment Variable

Part of the process to enable CCI tracing is to specify the degree of information that will be traced, which can be done by setting the CCITRACE environment variable as follows:

CCITRACE=options

where:

options
Any, or all, of the following:
/F or -F | logs the details of CCI API calls to the trace file. The default is OFF, unless any other trace option is specified, in which case it is ON.
/P or -P | logs the details of protocol-level calls to the trace file. The default is OFF. If this flag is OFF, 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.
/D or -D logs the contents of all buffers passed to and from the CCI functions. The default is OFF.
Warning: This type of tracing may not produce the desired results if the application has been coded to prohibit data tracing.

The cci.ini file ([ccitrace_base] section) can also be used to control trace options, but any values specified by the CCITRACE environment variable will take precedence.

Parent topic: Enabling CCI Tracing
Related information
Tracing Options for cci.ini
Activating CCI Tracing for Fileshare
To Enable CTF Tracing


Tracing Options for cci.ini

Part of the process to enable CCI tracing is to specify the degree of information that will be traced, which can be done by configuring the [ccitrace-base] section of the CCI configuration file, cci.ini. The options are:

Option | Value | Meaning
force_trace_on | yes or no | If yes, details of CCI API calls are logged to the trace file. The default is no. Unless this option is specified, no tracing will be generated, even if the other options are set to yes.
protocol_trace | yes or no | If yes, details of protocol-level calls are logged to the trace file. If this option is yes, the level of function tracing may be greatly increased. The default is no.
data_trace | yes or no | If yes, the contents of all buffers passed to and from the CCI functions are logged. The default is no. Warning: This type of tracing may not produce the desired results if the application has been coded to prohibit data tracing.

For example, to enable CCI API tracing and data tracing, but not protocol-level tracing, add the following:

[ccitrace-base]
force_trace_on=yes
protocol_trace=no
data_trace=yes

The CCITRACE environment variable can also be used to control trace options, and any values specified by the variable will take precedence over values in cci.ini.

Parent topic: Enabling CCI Tracing
Related information
CCITRACE Environment Variable
Activating CCI Tracing for Fileshare
To Enable CTF Tracing


Activating CCI Tracing for Fileshare

To activate CCI tracing on a Fileshare server, you must add the following /tr parameter setting to the Fileshare Server configuration file:

/tr cci

Prior to starting the Fileshare Server, you also need to have enabled CCI tracing as described in Enabling CCI Tracing.

To prevent unauthorized access to the CCI information traced through Fileshare, you are prompted for the supervisor password (for user-id FSVIEW) when you invoke a Fileshare Server with CCI tracing enabled. If the password is accepted, CCI tracing is enabled, and a second prompt asks if CCI tracing should be activated immediately or not.

CCI tracing can be toggled on and off using the F3 key.

Parent topic: Enabling CCI Tracing
Related information
CCITRACE Environment Variable
Tracing Options for cci.ini


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
CCI Tracing
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 c:\ccilogs\.

errlog_path=yes,c:\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,c:\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
CCI Tracing
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


PL/I Programming

  • Open PL/I User's Guide
Parent topic: Micro Focus Enterprise Server 2.3 Update 1 for Windows


Open PL/I User's Guide

This book shows you how to operate Micro Focus's Open PL/I application.

  • Using Open PL/I
    This chapter explains how to install the Open PL/I Compiler and how to enter, compile, link, and run Open PL/I programs.
  • Language Concepts
    This chapter describes the Open PL/I language implementation for your system. For detailed information on the Open PL/I programming language, see your Open PL/I Language Reference Manual.
  • Open PL/I SQL Options
    This chapter describes the SQL Options available with Open PL/I. These include the DB2 SQL Option that provides support for IBM's DB2 on UNIX.
  • Open PL/I Compiler Diagnostic Messages
    This appendix describes the format of Open PL/I compiler diagnostic messages and their levels.
  • Open PL/I Run-time Error Messages
    This appendix contains information on Open PL/I run-time errors, UNIX system error codes, and Open File Manager (OFM) error codes. Run-time errors are detected by the Open PL/I run-time system, or by the operating system.
  • Value Table for ONCODE Built-in Function
    You may use the ONCODE built-in function in any unit to determine the nature of the error condition that caused invocation of that ON-unit. This appendix lists the values returned by the ONCODE built-in function and the errors or conditions corresponding to each value.
  • National Locale Support
  • Character Sets
    This appendix provides you with the ASCII equivalents of EBCDIC characters.
  • Environment Variables
  • Migration to Micro Focus File Formats
Parent topic: PL/I Programming


Using Open PL/I

  • Compiling a Program
  • Linking a Program
  • Running a Program
  • Program Debugging
  • Using Open PL/I with Other Software Products
  • Using the PL/I Message User Exit
  • Compiling, Linking and Debugging of Fetchable Procedures
  • Data File Tools Support for PL/I
    Describes the Data File Tools support for PL/I programs.
  • EXEC DLI Support in PL/I
    Describes EXEC DLI support in PL/I.
Parent topic: Open PL/I User's Guide


Compiling a Program

Attention: You must recompile and relink your Open PL/I applications to use them with this Enterprise Developer release.

Open PL/I consists of the following executable programs:

  • The Open PL/I Macro Preprocessor, named mfpp
  • An Include Preprocessor, named mfinclpp
  • A CICS Preprocessor
  • An HCO for DB2 LUW Preprocessor
  • A DL/I Preprocessor
  • An OpenESQL Preprocessor
  • A DB2 Preprocessor, named mfdb2 (deprecated)
  • The Compiler itself, named mfpli
  • A command-line driver that allows compiling and linking in one step, named mfplx

Note that in the names mfpli and mfplx the fourth character is the lowercase of the letter "L".

mfpp is executed prior to the compilation, and its output is passed to the Open PL/I Compiler.

You can run mfpp directly, but the recommended way to run it is by use of the -macro option with mfplx when you are compiling your program. This allows the mfpp output to be automatically directed to the Compiler.

mfpli allows only one filename, accepts only Open PL/I Compiler options, and requires a separate ldpli step. The suffix of the filename to be compiled by mfpli is not restricted.

mfplx allows multiple filenames and accepts mfpli options as well as many standard UNIX or Windows system compiler and linker options, such as -c and -o. The -c option specifies compilation without linking. When -c is used, the -o option is passed to the compiler; when -c is not used, -o is passed to ldpli. Note that some file name suffixes are restricted to .pl1 or .pli when using mfplx.

The Include Preprocessor processes selected or default "include" statements and produces a deck that can then be treated as a single source file by another preprocessor or the Open PL/I Compiler. It is normally run under control of mfplx and is always run as the first preprocessor. Its output becomes the input to the next preprocessor or the Open PL/I Compiler.

Note: The best way to determine the command needed to invoke this preprocessor directly is to use the -# option on the mfplx command and use the command it would have used. For example:
mfplx -# -incl myprog.pli –isuffix .inc –path e:\source\include –ppincl myprog.out –optincl sp

The CICS preprocessor converts EXEC statements into native PL/I code that is then possibly further macro processed and then finally compiled and linked.

The OpenESQL and DB2 preprocessors process SQL statements before the compilation.

See the following sections for descriptions of the syntax to invoke mfpp, mfpli, or mfplx.

  • Compiling in 64-Bit Mode
  • mfpp Syntax
  • mfpli Syntax
  • mfplx Syntax
  • Preprocessor Order of Execution
  • mfplx Options
  • Include Preprocessor Options
  • Macro Preprocessor Options
  • CICS Preprocessor Options
  • HCO for DB2 LUW Preprocessor Options
  • DB2 Preprocessor Options (Deprecated)
  • Compiler Options
  • Compiler Listings
  • Open PL/I Compiler Implementation Limits
  • Open PL/I Compiler restrictions
    Describes permanent restrictions of the Open PL/I compiler
  • Compilation Statistics
  • Temporary Files
  • Optimization
Parent topic: Using Open PL/I


Compiling in 64-Bit Mode

On x64 Windows, when you open Start > All Programs > Micro Focus Enterprise Developer > Tools > Enterprise Developer Command Prompt (64-bit), the compiler and debugger that will be running in the background will be 64-bit and the output application will be 64-bit too.

Restriction:
  • -coffdebug compiler option is not supported on 64-bit Windows.
  • The deprecated mfdb2 preprocessor is not available on 64-bit Windows. Please use the EXEC preprocessor (invoked by -sql db2).
Parent topic: Compiling a Program


mfpp Syntax

The valid format for the mfpp command is:

mfpp [–ipath dir][-{isuffix|x} suffix] [–pp outfile]infile

where dir is a directory name, suffix defines a string to be appended to any unquoted filename in a %INCLUDE statement, infile specifies a source filename, and outfile specifies an output filename. At least one input file must be specified.

The preprocessor input is a file containing an Open PL/I source module, possibly including Open PL/I Macro Preprocessor statements. The preprocessor output is an Open PL/I source module containing no further preprocessor statements, but with the source code modified according to the semantics of the preprocessor statements that were encountered in the input file.

mfpp is usually run by use of the -macro option with mfplx.

Parent topic: Compiling a Program
Related information
Macro Preprocessor Options


mfpli Syntax

The valid format for the mfpli command is:

mfpli [option] ... file [option]...

where option represents a Compiler option and file represents any single specified source file. There is no restriction on the suffix of the filename. option arguments can go either before or after file. (An error may result if the -I or -o option appears before file without specifying a list filename or object filename.)

Parent topic: Compiling a Program


mfplx Syntax

The valid format for the mfplx command is:

 mfplx {option | source_file | object_file} ...

where option represents an Open PL/I Compiler option or a system Compiler or linker option.

source_file represents any specified source file. Files with a .pl1 or .pli suffix are passed to mfpli. On UNIX systems, files with an .s suffix are passed to the system assembler. On Windows systems, files with an .asm suffix are passed to the system assembler.

mfplx supports wildcard characters and indirect files (@files).

object_file represents any specified object file (with an .o suffix for UNIX systems or a .obj suffix for Windows systems) or any specified library (with an .a suffix for UNIX systems or an .lib suffix for Windows systems). Files with an .o (or .obj) or an .a (or .lib) suffix are passed to mfpli, as are specified files with unknown or absent suffixes. The command line that mfpli constructs for each of these invocations is limited to 4096 characters. The .o files can be linked (possibly with other object files and/or libraries) using ldpli or mfplx -o.

mfplx processes options in one of the following ways:

  • Passes the option to the preprocessor (mfpp).
  • Passes the option to the compiler (mfpli).
  • Passes the option to the linker (ldpli).
  • Executes the option (for example, -c) in a fashion similar to cc.
  • Ignores the option.

Program execution begins at the main entry point.

Parent topic: Compiling a Program
Related information
Compiler Options
Compiling a Program
Linking a Program
Main Procedure


Preprocessor Order of Execution

The Open PL/I preprocessors are run by mfplx in the following order:

  1. Open PL/I Include Preprocessor
  2. Open PL/I Macro Preprocessor
  3. DL/I Preprocessor
  4. OpenESQL Preprocessor
  5. CICS Preprocessor
  6. Open PL/I Macro Preprocessor
  7. DB2 Preprocessor
    Note: The DB2 Preprocessor is deprecated and will be removed in a future release.

The ordering of the Compiler switches you use has no impact.

You may change the order, if necessary, by separately invoking the preprocessor you choose.

It is recommended that you run the preprocessors in this order via mfplx, but if you want to run the preprocessors separately, run mfplx with the preprocessor arguments you want and the -# flag to see what command lines are generated.

The running of the preprocessor is controlled by the following flags:

  • -incl [-ppincl [output_file]]
  • -macro [-pp [output_file]]
  • -dli [-ppdli [output_file]]
  • -cics [-ppcics [output_file]]
  • -sql [-ppsql [output_file]]
  • -db2 [-ppdb2 [output_file]]

-incl, -macro, -dll, -cics, -db2 and -sql cause respective preprocessors to run. -ppincl, -pp, -ppdli, -ppcics, -ppdb2 and -ppsql cause the preprocessor's output to be kept and the optional output_file says to give the output file a particular name.

  • Examples
Parent topic: Compiling a Program


Examples

Example 1: Equivalent to an ordinary compilation with -macro.

The command line

mfplx -macro sample.pl1 -#

produces:

mfpp sample.pl1 -pp sample.pp
mfpli sample.pp -o sample.o
rm -f sample.pp
ldpli sample.o

Example 2: Equivalent to an ordinary compilation with -macro and two preprocessors.

The command line

mfplx -db2 -macro sample.pl1 -cics -#

produces:

mfpp sample-pl1 -pp sample.pp
mfcics -i sample.pp -o sample.pp1
mfpp sample.pp1 –pp sample.pp2
mfdb2 -i sample.pp2 -o sample.pp3
mfpli sample.pp3 -o sample.o
rm -f sample.pp sample.pp1 sample.pp2 sample.pp3
ldpli sample.o

Example 3: Run macro preprocessor and CICS preprocessor only, preserving the intermediate output files.

The command line

mfplx -E sample.pl1 -macro -cics -#

produces:

mfpp sample.pl1 -pp sample.pp
mfcics -i sample.pp -o sample.pp1
mfpp sample.pp1 –pp sample.pp2

Example 4: Ordinary compile, preserving CICS preprocessor output.

The command line

mfplx -cics -ppcics cicsout.out sample.pl1 -#

produces:

kixplt -i sample.pl1 -o cicsout.pl1
mfpli cicsout.pl1 -o sample.o
ldpli sample.o

Example 5: Multiple compilations.

The command line

mfplx -db2 -cics sample.pl1 sample2.pl1 -#

produces:

sample.pl1:
mfpp sample.pl1 -pp sample.pp
mfcics -i sample.pp -o sample.pp1
mfpp sample.pp1 -pp sample.pp2
mfdb2 -i sample.pp2 -o sample.pp3
mfpli sample.pp3 -o sample.obj
del sample.pp sample.pp1 sample.pp2 sample.pp3
sample2.pl1:
mfpp sample2.pl1 -pp sample2.pp
mfcics -i sample2.pp -o sample2.pp1
mfpp sample2.pp1 -pp sample.pp2
mfdb2 -i sample.pp2 -o sample2.pp3
mfpli sample2.pp3 -o sample2.obj
del sample2.pp sample2.pp1 sample.pp2 sample2.pp3
ldpli -db2 sample.obj sample2.obj
Parent topic: Preprocessor Order of Execution


mfplx Options

mfplx allows multiple filenames and accepts mfpli options as well as many standard UNIX or Windows system compiler and linker options, such as -c and -o. The -c option specifies compilation without linking. When -c is used, the -o option is passed to the compiler; when -c is not used, -o passes to ldpli.

On UNIX, mfplx always passes the -map option to the compiler for a storage allocation map in the listing file.

On Windows, when using the -c option for compiling without linking, mfplx passes the -map option to the compiler for a storage allocation map in the listing file. When linking is performed, mfplx passes -map to ldpli to create a loader map.

Some of the options available for use with the mfplx command are explained in the following table.

Option | Explanation
-# | Shows preprocessor(s) and compile/load commands (echo only).
-c | Specifies compilation without linking.
-db2 | Indicates using the mfdb2 preprocessor and/or link with mfdb2 DB2 support. (deprecated)
-dli | Runs the DL/I preprocessor and/or links with mfexecpp DL/I support.
-help | Prints help text on STDOUT.
-incl | Invokes the Include preprocessor.
-l | Specifies an include search path.
-macro | Runs the PL/I macro preprocessor.
-nodebuginfo | Tells mfplx not to generate %FILE, %LINE, %SDEBUG and %RDEBUG information.
-nomacro | Suppresses the invocation of the Open PL/I Macro Preprocessor.
-O | Selects optimization level 0,1, 2, or 3 (equivalent to -opt.)
-pp | Specifies PL/I macro preprocessor's output filename and saves it.
-ppdb2 | Specifies DB2 SQL preprocessor's output filename and saves it.
-sql | Indicates using the mfexecpp SQL preprocessor (for DB2, OCI, or ODBC).
-systemcics | Compiles and/or links to execute under CICS.
-systemims | Compiles and/or links to execute under IMS.
-systemmvs | Compiles and/or links to execute under MVS.
-v | Shows the version number of the compiler.
Parent topic: Compiling a Program


Include Preprocessor Options

The Include pre-processor has the following general syntax:

mfinclpp input-file-name -incl [-ppincl output-file-name] [-optincl incl-pp-options]

The only required option is the input-file-name. The other options are:

Option | Explanation
-ppincl output-file-name | Overrides the default output file name, which will be input-file-name with an extension of .ppi. Example: -ppincl myprog.dek
-optincl options-string Specifies which INCLUDE statements you wish the Include preprocessor to process. options-string is any or all of the following single letters (upper or lowercase) specified in any order without any intervening commas or spaces:
  • S - processes EXEC SQL INCLUDE statements
  • P - processes Panvalet ++INCLUDE statements. The ++INCLUDE statement must be on a line by itself, must be all uppercase including member-name, and must have the following syntax:
    [spaces] ++INCLUDE [spaces] member-name [spaces]  [;]
  • L - processes Librarian -INC statements. The -INC statement must be on a line by itself, must be all uppercase including member-name, and must have the following syntax:
    [spaces] -INC [spaces] member-name [spaces]  [;]
  • I - processes PL/I %INCLUDE and %XINCLUDE statements. Full mainframe syntax for these statements is supported.

If this option is not specified, SPLI is the default. i.e. all of these INCLUDE statements are processed.

  • Examples
Parent topic: Compiling a Program


Examples

Example 1:

mfexecpp myprog.pli –isuffix .inc –path e:\source\include –ppincl myprog.out –optincl si

Will process only EXEC SQL INCLUDE, %INCLUDE and %XINLUCE statements. ++INCLUDE and -INC will not be processed.

Example 2:

mfexecpp myprog.pli –isuffix .inc –path e:\source\include –ppincl myprog.out –optincl ps

Will process only ++INCLUDE and EXEC SQL INCLUDE statements.

Example 3:

mfexecpp -incl myprog.pli –isuffix .inc –path e:\source\include

Will process all types of include statements producing myprog.ppi as the output file.

Parent topic: Include Preprocessor Options


Macro Preprocessor Options

The options available for use with the mfpp command are explained in the following table. The -ipath and -suffix options obey the rules that apply when they are invoked as compiler options.

Option | Explanation
-currency_symbol | Provides a currency symbol for picture specification. It can take the character, decimal number, or hex constant of the form 0xDD, for example, -currency_symbol £, -currency_symbol 163, -currency_symbol 0xa3.
-define name[=value] mynum[='value' (value)] Using name[=value] causes value to be used in place of name wherever the identifier name appears.

Using mynum[='value' (value)] defines a preprocessor variable called MYNUM to the PL/I Macro Preprocessor. The presence or absence of single quotes around the value determines whether the defined variable is of type CHAR or type FIXED.

For example, -define mynum='1234' defines the variable as type CHAR. It is equivalent to coding the following in the PL/I program processed by the macro preprocessor:
%DCL MYNUM CHAR;
%MYNUM = '1234';
To define a FIXED type variable, omit the quotes and use a numeric value. For example, -define mynum=1234 is equivalent to coding the following in the PL/I program processed by the macro preprocessor:
%DCL MYNUM FIXED;
%MYNUM = 1234;
-incafter filename | Allows for the use of an include file without having to modify sources. The named file is infused as the first line of source.
-includes | Tells the preprocessor to process %INCLUDE statements.
-ipath dir | The -ipath and -isuffix options obey the rules that apply when they are invoked as Compiler options. This option specifies the folder location to search for include files.
-isuffix suffix (or -x suffix) | The -ipath and -isuffix options obey the rules that apply when they are invoked as compiler options.
-margins I,r Sets the margins within which characters of the source file are interpreted as source code and outside which all characters are ignored by the Compiler. l is the column number of the leftmost character and r is the column number of the rightmost character to be interpreted as source code. Note that, if tabs are used, each tab is counted as a single character.

The -margins option on a *PROCESS card is ignored if the macro pre-processor is in use (either by executing mfpp or mfplx with the -macro option); in this case, if the source margins are not 1,256, the actual margins must be specified with the -margins option.

-nodebuginfo | Specifies that the preprocessor will not generate the normal debug information that it passes to the Compiler. This is useful if you wish to debug using the post-preprocessing PL/I source file rather than the original source file.
-noincludes | Tells the preprocessor not to handle %INCLUDE statements.
-[no]namesstring1 [string2] Provides extended character support. For example,
-names 'string1' ['string2']
where string1 are extralingual characters to add to identifiers, and string2 are optional corresponding uppercase characters. Hex constants of the form 0xDD are accepted in place of the strings. The default is -names.
-not_symbol | Provides a not symbol. It can take the character, decimal number, or hex constant of the form 0xDD.
-or_symbol | Provides an or symbol. It can take the character, decimal number, or hex constant of the form 0xDD.
-pp outfile (or -o outfile) | Names the output file the name you specify with outfile. If -pp is not specified, the default name of the file is xxx.pp, where xxxis the input filename up to, but not including, the last "." (if any) in the name. For example, if the input filename is prog.pl1, the default output filename is prog.pp.
-T | Causes the preprocessor to examine a %INCLUDE file name for the characters @, #, and $, and to replace @ with A, # with N, and $ with D.
-undefine name | Removes a definition for name, if name was created by a -define option, and leaves the identifier name in the source as name. It does not preclude a %REPLACE statement or %name=expr from changing the value of name.
-variant string | Supplies a string to be used in place of the VARIANT built-in function.
Parent topic: Compiling a Program


CICS Preprocessor Options

The CICS Preprocessor options are explained in the following table.
Option | Explanation
-# | Displays the mfexecpp command line.
-bigendian | Default to BIGENDIAN integers. Note: It is applied by default.
-deb | Allows debugging.
-i | Specifies input file.
-margins | Specifies the margins (-margins left,right)
-native | Default to LITTLEENDIAN integers.
-nonnative | Default to BIGENDIAN integers.
-not_symbol | Selects alternate NOT symbol
-o | Specifies output file.
-or_symbol | Selects alternate OR symbol
Parent topic: Compiling a Program


HCO for DB2 LUW Preprocessor Options

Syntax

Use this syntax to set an HCO for DB2 LUW preprocessor option for the PL/I compiler.

mfplx pliProgName –sql db2 –optsql "DB2PrecompilerOption [...]"

Required Options

Since the HCO for DB2 LUW preprocessor must connect to the DB2 LUW server to convert EXEC SQL statements to API calls, you must use the DB option for PL/I when building applications using SQL.

Examples

These examples specify a server named SAMPLE to connect to and compiles programs named sample1 and sample2 respectively:

mfplx sample1.sqb –sql db2 –optsql "DB=SAMPLE"
mfplx sample2.sqb –sql db2 –optsql "DB=SAMPLE"
Note: You do not need to link with db2api.lib library as PL/I dynamically loads all required code.
Parent topic: Compiling a Program
Related concepts
HCO for DB2 LUW Preprocessor


DB2 Preprocessor Options (Deprecated)

The DB2 Preprocessor options are listed in the table below:

-action | Refer to the IBM DB2 documentation.
-bind | Specifies that a bind file should be created.
-bindname | Specifies name of bindfile to create.
-block | Specifies type (unambig, all or no) of row blocking.
-catalog | Refer to the IBM DB2 documentation.
-charsub | Refer to the IBM DB2 documentation.
-connect | Specifies if the CONNECT statement should be of type 1 or 2.
-collection | Specifies the collection schema name.
-datetime | Specifies date/time format (def, usa, eur, iso, jis, loc).
-dbname | Specifies name of database to preprocess against.
-dec | Refer to the IBM DB2 documentation.
-decdel | Refer to the IBM DB2 documentation.
-degree | Refer to the IBM DB2 documentation.
-disconnect | Refers to disconnections (explicit, automatic or conditional).
-dynamicrules | Refer to the IBM DB2 documentation.
-explain | Refer to the IBM DB2 documentation.
-explsnap | Stores an Explain snapshot (no, all or yes)
-funcpath | Specifies functional path for types and functions in static SQL.
-insert | Refers to data buffering (def or buf).
-isolation | Specifies isolation level (ss, rr, ur).
-level | Refer to the IBM DB2 documentation.
-nobind | Specifies that no .bnd file is created.
-nooptimize | Specifies that no SQLDA initialization optimizations are done.
-package | Causes package creation.
-packagename | Specifies name of package. Implies -package.
-optimize | Specifies that SQLDA initialization optimizations are done.
-optlevel | Same as -optimize. Impacts initializations of SQLDAs.
-owner | Refer to the IBM DB2 documentation.
-queryopt | Optimization of static SQL. The default level is 5.
-qualifier | Refer to the IBM DB2 documentation.
-release | Refer to the IBM DB2 documentation.
-replver | Refer to the IBM DB2 documentation.
-retain | Refer to the IBM DB2 documentation.
-schema | Refer to the IBM DB2 documentation.
-sqlerror | Specifies action following error(s).
-sqlflag | Reports on deviations on SQL syntax.
-sqlrules | Refers to connects (std or db2).
-sqltwop | Performs two passes because variable usage precedes declarations.
-sqlwarns | Refers to dynamic SQL.
-stds | Refer to the IBM DB2 documentation.
-syncpoint | Refers to commits or rollbacks (onephase, none, twophase)
-syntax | Suppresses package or binding. Validity checking.
-text | Refer to the IBM DB2 documentation.
-validate | Refer to the IBM DB2 documentation.
-version | Refer to the IBM DB2 documentation.
Parent topic: Compiling a Program


Compiler Options

Note: When compiling from the command line, enclose any compiler option values that contain special characters (including spaces) in double quotes (" "). For example, enter:
-optexec  vtrace,plitest(b 10)

and

-optexec  plitest(b 10)

as:

-optexec  "vtrace,plitest(b 10)"

and

-optexec  "plitest(b 10)"

Compiler option values can always be enclosed in double quotes even if containing no special characters. However, do not use single quotes to enclose compiler option values.

The list below describes each of the Compiler options and its default setting, when applicable.

-#
Provides information on how the Compiler and linker would be invoked without actually invoking them. This option also shows which UNIX options are translated to Micro Focus options; for example, when the standard UNIX -O option is given on the driver command line, it is translated on the Compiler invocation line as -opt.
-adt
-adt [adt-filename]

Generates a file containing the data structures processed by the PL/I compiler. If adt-filename is not specified, a file with the name program-name.adt is generated. This file is consumed by the Record/Segment Layout Editor, which creates Segment Layout Files (SLF) and Record Layout Files (STR) using these PL/I structure descriptions. Data File Tools can then use these layout files to aid in processing/editing the segments or records (Data File Convert, Data File Editor, IMS Database Editor, IMS Database loader).

Use the ADT file with the Layout Editor to create SLF and STR files.

-agginit
Performs initialization of aggregates compatible with 7.x versions of Open PL/I (scalar arrays only).

Example:

dcl myarr(4) fixed bin(31) static init (1);
put skip list (myarr);

results in:
             1               1               1               1

By default, without -agginit, only the first element is initialized.

-ascii
Specifies to use the ASCII character encoding for all character data. This option is set by default.
-bigendian
Specifies that all FIXED BINARY, CHARACTER VARYING, GRAPHIC VARYING and WIDECHAR VARYING items are implicitly declared with the BIGENDIAN data attribute, unless the NATIVE attribute is explicitly applied to a data item.
-bitsltr
Stores bit strings left-to-right within each byte. This is similar to Big Endian bit ordering (Intel only). The Intel default is to store bit strings right-to-left, but when the option is used, bit strings are stored left-to-right within each byte.
-c
Suppresses linking and produces a relocatable object file. This option applies to mfplx only.
-cics
Invokes the CICS preprocessor for EXEC CICS support. This allows EXEC CICS statements to be recognized and processed to generate native PL/I source code.
-coffdebug
Emits line number information for the Visual Studio debugger to enable breakpoints, statement tracing, and call stack information of Open PL/I source code.
Restriction:
  • Evaluation of variables is not supported.
  • -coffdebug is not supported on 64-bit Windows.
-compact_msgs
Do not break the line for messages.
-currency_symbol
Allows an alternate currency symbol for picture specification. It can take a character, decimal number, or hex constant of the form 0xDD, for example, -currency_symbol £, -currency_symbol 163, -currency_symbol 0xa3.
-db2
Invokes the DB2 preprocessor, mfdb2. The default DB2 preprocessor output file name is xxx.pp2, where xxx is the name of the source file. If the -ppdb2 option is not specified, the file xxx.pp2 is deleted after the compilation phase is completed. The -db2 option applies to mfplx only.
Warning: This option is required for the mfdb2 preprocessor, which is deprecated. Please use the EXEC preprocessor (invoked by -sql db2)
-default_binary
Causes the BINARY attribute to be assumed if the FIXED attribute is specified without BINARY or DECIMAL.
-default_decimal
Causes the DECIMAL attribute to be assumed if the FIXED attribute is specified without BINARY or DECIMAL. This option is the Compiler default.
-defext
Causes external variables to be defined in the data section. You must use this option for programs using external files.

The -defext option causes the initialized values of STATIC EXTERNAL variables and external file constants to be defined. Each STATIC EXTERNAL variable that has an INITIAL value must be declared in one and only one module that has been compiled with -defext. Failure to do so causes the INITIAL value to have no effect. The default is -nodefext.

Also, each file constant must be declared in one and only one module that has been compiled with -defext. When -defext is used, file attributes specified in the file declaration merges with attributes specified when the file opens. This is critical when doing VSAM/INDEXED I/O.

-dli
Invokes the DL/I preprocessor for EXEC DLI support. This allows EXEC DLI statements to be recognized and processed to generate native PL/I source code. This option is processed and supported by the EXEC preprocessor (EXEC PP).
-dll
Generates an object that can be used as a fetchable procedure. Use -dll to build shared fetchable procedure objects based on your operating system.
-E
Causes any specified preprocessors (-macro, -db2) to be run on the source file, and saves their output, but stops without running the Compiler.
-ebcdic
Specifies to use EBCDIC character encoding for all character data.
Note: The WIDECHAR and GRAPHIC data types are not supported with the -ebcdic compiler option.
-err_on_stdout
Displays or prints compiler error messages to STDOUT instead of STDERR.
-exp
Produces an expanded listing of the generated code in the form of assembly language statements in the listing file.
-f
Synonymous with -flag.
-fb7asfb15
Treats Fixed Binary (7) as Fixed Binary (15). Use for backward compatibility with previous versions of Open PL/I.
-fbmaxp n
Specifies the maximum Fixed Binary precision. The values can be:
31
Sets the maximum Fixed Binary precision to 31. This is the Open PL/I default.
63
Sets the maximum Fixed Binary precision to 63 and enables Fixed Binary (63) support.

You can also use -fixed_bin_max_p as a synonym to -fbmaxp.

-fdasfb
Causes Float Decimal data to be internally coded as Float Binary. This option produces much faster code but loses precision in the least significant digits of arithmetic results. -fdasfb is the default. See also the -nofdasfb option.
-fdmaxp n
Specifies the maximum FIXED DECIMAL precision n. Recommended values are:
15
The z/OS default.
18
Open PL/I default for Enterprise Developer release 2.1 and earlier.
31
Open PL/I default for Enterprise Developer release 2.2 and later.

Fixed decimal precision 31 is the maximum allowed.

You can also use -fixed_dec_max_p as a synonym to -fdmaxp.

-fixed_bin_max_p
The same as -fbmaxp.
-fixed_dec_max_p
The same as -fdmaxp.
-flag
Specifies the minimum diagnostic level of messages. Diagnostics below this level are suppressed. Synonymous with -f.
-flag minimum diagnostic level
The minimum diagnostic level can be:
I
Emits diagnostic messages beginning at the Informational level (Lists all messages. This is the default).
W
Emits diagnostic messages beginning at the Warning level.
E
Emits diagnostic messages beginning at the Error level.
S
Emits diagnostic messages beginning at the Severe level.
-fmaxp
Causes floating-point precision to be used for the trigonometric built-ins and for the following arithmetic built-ins: EXP, LOG, LOG10, LOG2, SQRT. -fmaxp is the default. Use -nofmaxp for the standard PL/I conversion rules for the trigonometric and the named arithmetic built-ins.
-full_list
This option tells the macro preprocessor to omit %NOLIST directives normally placed before code included by the %INCLUDE statement, thereby allowing the included code to be visible in the compilation listing.
-graphic
Enables support for the GRAPHIC data type.
Note: EBCDIC data and constants in conjunction with -graphic is not supported .
-help
Prints out a list of available compiler options to the console or STDOUT output, and to EXIT.
-highbif
This option allows changing the value returned by the HIGH() built-in function. For example, -highbif 127 (the default value is 255; the value 127 may be used for compatibility with earlier versions of Open PL/I).
-incl
Invokes the Include preprocessor which will process selected or default include statements and produce a deck that may then be treated as a single source file by another preprocessor or the Open PL/I Compiler.
-ipath dirlist
Directs the Compiler to search specified directories for files to be included in the source program text by use of the %INCLUDE statement. dirlist is an ordered list of directories of the form
dirname[:dirname] ...

The -ipath option instructs the Compiler to use these directories in the specified order in its search for files to satisfy %INCLUDE statements (except in cases where an absolute directory path is specified in the %INCLUDE statement).

For example, suppose the source program contains:

%INCLUDE partlist;

and the Compiler invocation command is:

mfplx source_file -ipath .:/u/libr1:/u/libr2

In this case, the Compiler will first search for "PARTLIST" in the current working directory, then /u/ libr1, and finally /u/ libr2. If that fails, it will search for "partlist" (lowercase) in the same directories.

In a Windows environment, the equivalent Compiler invocation is:

mfplx source_file -ipath .;drive:\libr1;drive:\libr2
-ipubr
Causes bits for unsigned integers created using INT or POSINT and bit strings returned with UNSPEC to be inversed.
-isuffix string
Causes string to be appended to the filename specified in %INCLUDE statements, except those in which the quoted filename form of the %INCLUDE statement is used.

For example, suppose the source program contains:

%INCLUDE partlist;

and the Compiler invocation command is:

mfplx source_file -isuffix .INC

In this case, the Compiler searches for a file named partlist.inc.

-l [ file]
Produces a Compiler listing where file is the name of the file to which the listing is output. If you do not supply a filename, you must place this option after the source filename on the command line; otherwise, an error message appears. The default name of the file containing the listing is xxx.list, where xxx is the source filename (excluding the pathname) up to, but not including, the last "." (if any) in the name. For example, if the source filename is prog.pl1, the default listing is prog.list (prog.lst for Windows systems). A Compiler listing is produced by default whenever -exp, -map, or -xref is specified.
-laxbased
Disables storage checking of BASED variables. This is Open PL/I default. See also –nolaxbased.
-laxdefined
Disables type and storage checking of DEFINED variables. This is Open PL/I default. See also –nolaxdefined.
-laxinit
Disables dependency ordering of automatic initializers in block prologue. The declaration order is used.
-longint
Changes the default precision of Fixed Binary variables from (15) to (31).
-lowercase
Converts all uppercase names of internal and external variables and constants to lowercase.
-macro
Invokes the Open PL/I Macro Preprocessor, mfpp. The default preprocessor output file name is xxx.pp, where xxx is the name of the source file. If the -pp option is not specified, the xxx.pp file is deleted after the compilation phase is completed. The -macro option applies to mfplx only.
-map
Does one of the following:
  • When used without a colon or any arguments, -map produces a storage allocation map at the end of the listing file.
  • When used with a colon and an argument, for example -map:filename (where filename is the filename of a linker map file), this option passes to ldpli and to generate a linker map for the specified filename.

-map add -map:filename can be used together.

-margins l,r
Sets the margins within which characters of the source file are interpreted as source code and outside which all characters are ignored by the Compiler. l is the column number of the leftmost character, and r is the column number of the rightmost character to be interpreted as source code. Note that if tabs are used, each tab is counted as a single character. The -margins option can be overridden by a *PROCESS statement in the source.
Note: There must be no spaces around the comma separating the left and right margin.
-maxmsg
Specifies the maximum number of diagnostics of a specified severity or higher which will be produced during compilation.
-maxmsg Level,n

where Level is one of I, W, E, S as follows:

I
Counts all compiler messages starting at I-level (Informational) against the maximum.
W
Counts all compiler messages starting at W-level (Warning) against the maximum.
E
Counts all compiler messages starting at E-level (Error) against the maximum.
S
Counts only S-level (Severe) against the maximum.
n

The maximum number.

The default is -maxmsg W,1000.

Compilation terminates if the number of messages exceeds the maximum number allowed. If messages are below the specified severity, they are not counted in the number. The value of n can range from 0 to 32767. If you specify 0, the compilation terminates when the first error of the specified severity is encountered.

An unrecoverable A-level (Abort) error message always results in termination.

-names
Adds extralingual characters to identifiers via the compiler options, similar in nature to *PROCESS NAMES().

Example:

-names 'string1' [ 'string2' ]
string1
Extralingual characters to add to identifier.
string2

Corresponding upper case characters. Optional.

The default is:

-names '$@#' '$@#'

For additional characters you must specify the default $@# or subset if desired, plus the additional lingual characters.

-names '$@#?'

For convenience, hex constants of the form 0xDD..DD are accepted in place of the strings above.

-names 0x402324a3
-nest
Causes the nesting of DO ... END, PROC ... END, and so on to be shown in the listing file. See the -l option for more information about the listing file.
-nodebuginfo
Tells the Compiler to not break the line for %FILE and %LINE information.
-nodefext

The -nodefext option prevents definition of initialized values of STATIC EXTERNAL variables and external file constants (default). See the -defext compiler option for more information.

Also, each file constant must be declared in one and only one module that has been compiled with -defext. When -defext is used, file attributes specified in the file declaration will be merged with attributes specified when the file is opened. This is critical when doing VSAM/INDEXED I/O.

-nofdasfb
Causes Float Decimal data to be internally coded as Binary Coded Decimal. The default setting is -fdasfb.
-nofmaxp
Causes standard PL/I conversion rules to be used to determine the precision of trigonometric and certain arithmetic built-ins. The default is -fmaxp.
-noincludes
Tells the Compiler and/or macro preprocessor not to include the contents of %INCLUDE files in the compiled source.
-nolaxbased
For BASED variables declared using the form BASED (ADDR(x), enables storage checking with the base reference “x”. –laxbased is the Open PL/I default.
Note: Any of the options -cics, -sql, -dli, -mvs, and/or –ims imply –nolaxbased. This can be overridden when used in combination with –laxbased.

Example:

DCL S1 CHAR(10); DECLARE S2 CHAR(20) DEFINED (S1);

will result in an appropriate diagnostic.

-nolaxdefined
For DEFINED variables, enables both type and storage checking on DEFINED variable and the base variable. –laxdefined is the Open PL/I default.
Note: Any of the options -cics, -sql, -dli, -mvs, and/or –ims imply –nolaxdefined. This can be overridden when used in combination with –laxdefined.

Example:

DCL X FIXED BIN (15); DECLARE Y FIXED BIN (31) BASED (ADDR(X));

will result in an appropriate diagnostic.

-nolaxdcl
Tells the Compiler to not allow compiler declarations for undeclared variables.
-nolaxinit
Enables dependency ordering of automatic initializers in block prologue. This is the Open PL/I default.
-nomacro
Suppresses the invocation of the Open PL/I Macro Preprocessor. The default is -nomacro.
-noobj
Compiles for syntax and semantic checking only. Does not produce an object file.
-noopt
Compiles without optimization. This is the default.
-norange
Suppresses generation of code to check the validity of subscript references and substring bounds. This option should be used after your program has been debugged to improve execution time performance. The default is -norange.
-noopt
Compiles without optimization. This is the default.
-not_symbol
Lets you specify an alternate NOT symbol. It can take a character, decimal number, or hex constant of the form 0xDD. See also %PROCESS in the Language Reference Manual.
-nounixdebug
Avoids generating the additional object file data needed to report source file and line number when a fatal run-time error occurs, or for use by the ONLOC built-in function.
-nounrefexternals
Prevents external entry symbols that are not referenced in the program from being generated in the object file. This is the default.
-nowarn
Suppresses all INFORMATIONAL and WARNING level diagnostics. This is equivalent to setting the –flag option to E.
-[no]xref
Tells the compiler to not include a cross-reference table of names that are used in the program. See the -xref compiler option for more information.
-O
Invokes the optimization phase of the Compiler. This option applies to mfplx only and is equivalent to the -opt option.
-o file
Names the object file the name you specify with file. If -o is not specified, the default name of the file is xxx.o, where xxx is the source filename up to, but not including, the last "." (if any) in the name. For example, if the source filename is prog.pl1, the default object filename is prog.o (prog.obj for Windows).

If -c is specified, the -o option is passed to the compiler; if -c is not specified, -o is passed to ldpli.

-opt [level]
Specifies the level of optimization by the Open PL/I Compiler, where level stands for the level (1 – 3) of optimization. The default setting is -noopt. If level is not included, the program is optimized at level 3. If -deb is specified, -opt 2 is the maximum level allowed. Note, -opt-deb is equivalent to -opt 2 -deb.
-optcics
Allows the CICS options to be passed to the CICS ECM
-optdli
Allows the DL/I options to be passed to the DL/I (IMS) ECM
-optexec {sub-option}[,sub-option]
Lets you specify options for the EXEC preprocessor. You can use the following for the -optexec option.
[NO]PLITEST
Tells the EXEC preprocessor to inject an automatic call to start the GUI CodeWatch debugger.

Using the -optexec option with the PLITEST parameter also lets you debug PL/I programs that run under CICS. During execution, the program stops at the first executable statement (either the PROCEDURE statement or the first statement following the PROCEDURE statement, depending on the execution environment). Specify the appropriate program source files and debug files with the CODEWATCH_SRCPATH and CODEWATCH_STBPATH environment variables when using PLITEST with this option.

NEWNAME(newname)
Specifies a name for the outermost external procedure in addition to other names that may have been specified on the PROCEDURE statement. Use this when the name on the procedure does not match the name of the executable. (newname) is the same name as the name of the executable.
trace
Causes the preprocessor to create a file source.trc where source is the name of your source file.
ctrace
Creates a trace file for submission to Technical Support if requested.
strace
Creates a log file from the internal functions called by the program.
vtrace
Creates a dynamic visual trace of the program.
-optsql
Allows the SQL options to be passed to the SQL ECM
-or_symbol
Lets you specify an alternate OR symbol. It can take a character, decimal number, or hex constant of the form 0xDD. See also %PROCESS in the Language Reference Manual.
-pass
Connects to a remote DB2 database. You can use this option with a specified username and password. The format is:
–pass myid.mypass

Where myid is the username and mypass is the password for the remote DB2 connection. mfplx first checks the -pass for a username/password and uses these values if specified. If not specified, it uses the values set for the DB2_USERNAME and DB2_PASSSWORD environment variables.

-pic
Generates position-independent code, suitable for linking into a shared library. This option is only available on Solaris, SUSE Linux and Red Hat Linux.
Use this option when compiling code for inclusion in a shared object.
-pl1g
Causes Open PL/I to retain the behavior of releases prior to Open PL/I 5.0 for certain operations that have been changed in such a way as to become incompatible with that former behavior. For example, TIME() returns a value including three fractional digits (thousandths), but -pl1g causes it to return only two fractional digits (hundredths).
-plitdli

Specifies IMS linkage when calling a PLITDLI entry point name rather than a user supplied PLITDLI. This option allows for DCL PLITDLI ENTRY; declared as such in the user program (without an entry descriptor list and/or return type).

-pp [file]
Specifies the file name for the output file of the Open PL/I Macro Preprocessor. An output file created with the -pp option is preserved after the compilation phase is completed. This option applies to mfplx and mfpp only.
-ppcics [file]
Specifies the file name for the output of the CICS preprocessor. An output file created with the -ppcics option is preserved after the compilation phase is completed. This option applies to mfplx only.
-ppdli[file]
Specifies the file name for the output of the DL/I preprocessor. An output file created with the -ppdli option is preserved for consumption by a downstream preprocessor or the PL/I compiler.
-ppdb2 [file]
Specifies the file name for the output of the DB2 preprocessor. An output file created with the -ppdb2 option is preserved after the compilation phase is completed. This option applies to mfplx only.
-ppsql [file]
Specifies the file name for the output of the SQL preprocessor. An output file created with the -ppsql option is preserved after the compilation phase is completed. This option applies to mfplx only.
-proto
Provides more extensive prototype checking on arguments vs. parameters in entry declarations (also assumed by default when using -vax).

Example:

declare myproc external entry(
      fixed binary(31),
      fixed binary(15),
      fixed binary(15));

   myproc: procedure(a,b,c);        /* mismatch diagnosed, -proto and -vax */
      declare a fixed binary(15);
      declare b fixed binary(15);
      declare c fixed binary(15);

   end t660;
-range
Validates all static array bound references at compilation time, and generates code to check the run time validity of all subscript references, and substring bounds. Note that the checking code slows down execution time performance.

Exceeding array or string bounds at run time, raise either the SUBSCRIPTRANGE or STRINGRANGE conditions as appropriate. Use this option to debug programming errors relating to subscripts and substrings. Use the -norange option for debugged code. The default is -norange.

-report [file]
Specifies the file name for the output of the Open PL/I Source Checker. If this option is not used, the output of the checker will be directed to the standard error file. This option applies to mfplx only.
-setnull n
Designates a null pointer value n to be returned by the NULL built-in function, where n is a decimal value. If this option is not specified, the value of the NULL built-in function is an address with all bits set to 1.
-setstack
Initializes automatic storage to zero.
-shortint
Tells the Compiler to set the default FIXED BINARY precision to 15.
-sql
Invokes the SQL preprocessor for EXEC SQL support. This allows EXEC SQL statements to be recognized and processed to generate native PL/I source code. This option is processed and supported by the EXEC preprocessor (EXEC PP). You can use the following for the -sql option.
odbc
Specifies an ODBC-compliant database.
db2
Specifies an IBM, DB2, or UDB database.
oci
Specifies an oracle "Call" interface database.
-stardesc
Tells the Compiler to produce argument descriptors for calls only when array bounds or string lengths in the parameter declaration are represented by the asterisk (*) symbol. (This was compiler behavior in releases prior to release 7.0.) When this option is not used, the Compiler produces descriptors for array, structure, and string arguments.
-stat
Prints Compiler statistics to the standard output as each Compiler phase completes.
-stbout
Generates an .stb file in the same directory as the output object file.
Note: You may need to set the CODEWATCH_STBPATH and CODEWATCH_SRCPATH variables to the appropriate locations when using this option.
-strip (ldpli)
Tells ldpli to not generate debugging information.
-structure_fillers
Tells the Compiler to produce warnings for structures containing fillers.
-systemcics

Specifies that this OPTIONS(MAIN) program will execute under the control of CICS. Such a program may have 0, 1, or 2 parameters, all of which must be POINTER. Such a program, almost always, will specify -cics and may also specify one or more of –sql and –dli.

-systemims
Specifies that this OPTIONS(MAIN) program will execute under the control of IMS. Such a program may have 0 thru n parameters, all of which must be POINTER. Such a program may also specify one or more of –sql and –dli.
-systemmvs
Specifies that this OPTIONS(MAIN) program will execute under the control of MVS. Such a program may have at most one parameter which must be CHAR(n) VARYING where “n” is not *. Such a program may also specify one or more of -cics, –sql and –dli.
-unaligned
This compile-time switch has been added for use on RISC architectures. This switch causes byte instructions to be generated for all based references, which might point anywhere in memory.
-unrefexternals
Causes external entry symbols to be generated in the object file, even if they are not referenced in the program.
-v
Prints information to stdout relating to the compilation and link-step phases. This option applies to mfplx only.
-variant string
Passes the variant string string to the Open PL/I Macro Preprocessor. This option applies to mfplx only.
-vax
Makes the following adaptations for programs originally written with Digital Equipment Corporations's PL/I Compiler for the VAX platform:
  • Enables Float Binary(24) as equivalent to Float Binary(23).
  • Enables Float Binary(53) as equivalent to Float Binary(52).
  • Causes the BINARY attribute to be assumed if the FIXED attribute is specified without BINARY or DECIMAL.
-warn
Does not suppress INFORMATIONAL and WARNING level diagnostics. This is equivalent to setting the -flag option to I. This is the default.
-window
Sets the value for the w window argument used in various date-related built-in functions.
w
Either a positive four-digit integer such as 1976 that represents the start of a fixed window or a negative integer that specifies a “sliding” window. For example, -window -50 indicates a window that starts 50 years prior to the year when the program runs.
-xref fullshort
Produces cross-reference information in the listing file and specifies the type of cross reference information produced. The cross-reference shows names used in the program with the numbers of the statements where they are either declared of referenced. Only label references on END statements are not included in the listing when using -xref.

Use full with -xref to include all identifiers and attributes in the listing. Use short with -xref to exclude unreferenced identifiers.

-zalign
Specifies z/OS aggregate mapping and alignment rules.
  • Affects mapping of structure members. z/OS structure mapping rules use a "shift-to-align" algorithm to minimize compiler inserted pad bytes for the alignment requirement of structure members. This differs from the default Open PL/I structure mapping rules described in the Structure topic, which are compatible with other UNIX and Windows compilers for inter-language compatibility.
  • Sets the default FLOAT BINARY single precision to 21 and the default FLOAT BINARY double precision to 53 ( implies -zfloat). The Open PL/I default is 23 and 52 respectively.
  • Specifies that the default alignment attribute for the CHAR, CHAR VAR, GRAPHIC, GRAPHIC VAR, WIDECHAR, WIDECHAR VAR and PICTURE data types is unaligned (implies -zchar). The Open PL/I default is aligned.
  • Implies double-word alignment of double precision FLOAT BINARY on Intel 32-bit systems (the Open PL/I and Intel native default alignment is word on Intel 32-bit systems)
  • Implies double-word alignment of AREA on Intel 32-bit systems (the Open PL/I default alignment is word on Intel 32-bit systems)

Structure Layout Example (Open PL/I default)

The following shows structure ST with size 8 bytes; member "C" is at offset 0 (byte alignment) and member "X" is at offset 4 (word alignment), with 3 compiler-inserted pad bytes between.

       1
       2      dcl 1 ST,
       3            2  C CHAR,
       4            2  X FIXED BIN(31);
       5

NAME             CLASS      SIZE      LOCATION    ATTRIBUTES

ST               BASED      8                    LEVEL 1 STRUCTURE
C               MEMBER      1         00000000   LEVEL 2 CHAR(1)
                            3         00000001    -pad-
X               MEMBER      4         00000004   LEVEL 2 FIXED BIN(31,0)

Structure Layout Example (-zalign)

The following shows structure ST with size 5 (8 bytes are allocated in memory); member "C" is at offset 0 (byte alignment) and member "X" is at offset 1 (word alignment). In this example each member is shifted by 3 bytes (OFFSET=3 as shown below) to properly align each member on its required boundary, thus minimizing (and in this case eliminating) compiler-inserted bytes. Effectively, the "shift-to-align" algorithm propagates pad bytes that fill natural alignment gaps between members toward the beginning of the structure. Pad bytes which have been shifted outside the structure (that is, preceding the first member) are known as "hang bytes".

       1
       2      dcl 1 ST,
       3            2  C CHAR,
       4            2  X FIXED BIN(31);
       5

NAME             CLASS      SIZE      LOCATION    ATTRIBUTES

ST               BASED      5                     LEVEL 1 STRUCTURE OFFSET=3
C               MEMBER      1         00000000    LEVEL 2 CHAR(1) UNALIGNED
X               MEMBER      4         00000001    LEVEL 2 FIXED BIN(31,0)
Note:
  • The use of this option is recommended only when structure mapping is required to match z/OS structure mapping rules. An example when required might be reading files imported from the mainframe containing record structures that have z/OS compiler-inserted (and possibly removed) pad bytes for alignment purposes.
  • If -zalign is used for the compilation of one module, it is recommended that all modules in a given program be compiled as such for compatibility. Mixing --zalign with compilation units in the same program may work, but this can be problematic if the modules compiled with -zalign are not "self-contained".
  • For adjustable structures (having REFER-extents or non-constant sized members), the -zalign "shift-to-align" algorithm will cause more code to be generated to access structure members with non-constant offsets (seen in the -map listing as (-V-) under the Location Field). Depending upon structure layout, the amount of code generated can be extensive as compared against the Open PL/I default mapping rules (when not using -zalign). Compiler optimization at a minimum level of -opt 2 is recommended.
Restriction:
  • For structures with multiple REFER-extents, compiler resources may be impacted resulting in a Compiler Abort. Please contact Micro Focus SupportLine.
Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.
-zchar
Specifies that the default alignment attribute for the CHAR, CHAR VAR , GRAPHIC, GRAPHIC VAR, WIDECHAR, WIDECHAR VAR and PICTURE data types is unaligned. The Open PL/I default is aligned.
Note: This affects storage requirements for CHAR VAR , GRAPHIC VAR, and WIDECHAR VAR. It also affects parameter and descriptor matching at CALL statements.

Example (Open PL/I default):

Dcl c  char;
Dcl sub entry (char unaligned);

    Call sub(c);  /* A dummy argument is created for “c” */

Dcl c  char;
Dcl sub entry (char aligned);

Call sub(c);  /* “c” is passed by reference */

Example (-zchar)

Dcl c  char;
Dcl sub entry (char unaligned);

    Call sub(c);  /* “c” is passed by reference */

Dcl c  char;
Dcl sub entry (char aligned);

Call sub(c);  /* A dummy argument is created for “c”  */
-zfloat
Specifies the Float Binary single precision default as 21; specifies the Float Binary double maximum as 53. The Open PL/I defaults are 23 and 52, respectively.
Note: Floating point precisions that are less than or equal to 21 are implemented as IEEE single precision floating point. Floating point precisions that are greater than 21 are implemented as IEEE double precision floating point.
-zp1
Causes all structures to be mapped as if the UNALIGNED attribute is specified at the level 1 structure level. The option is for compatibility with versions of DEC VAX PL/I.

Compiling with -zp1 effectively packs all structures so that any pad bytes used for data alignment are eliminated. This is useful when files originating from the mainframe have records in which the data items are packed or unaligned.

When -zp1 is set, the compiler needs to take certain precautions, especially on RISC architectures where misaligned data can cause a hardware exception.

The -zp1 compiler options affects the following:

  • All structure members are packed without any pad bytes for alignment as if the UNALIGNED attribute were specified at the level 1 structure level.
  • All based variables are treated as if unaligned.
  • All parameters are treated as if unaligned.
  • All Character Varying data items are treated as if unaligned. The Open-PL/I default alignment for CHAR VAR is HALFWORD which is the natural alignment of the leading fixed bin (15) length.

When using -zp1, to maintain consistency in passing arguments without modifying the source code, the compiler disables creating dummy arguments at call points when the argument is a structure member and the argument and parameter descriptors do not explicitly differ between the UNALIGNED and ALIGNED attributes.

Note: Using -zp1 can have an overall impact on performance. On RISC architectures such as SPARC and RS6000, the compiler must generate sequences of byte addressable instructions to access unaligned data items in the memory. On Intel, no changes are required for code generation, but additional clock cycles are required for the hardware to access misaligned data items.
Important: If you are using this release as an upgrade to Enterprise Developer 2.2 Update 1, after the upgrade you must rebuild any applications that are compiled using the –zp1 option.

The behavior of the –zp1 option has been reverted to that of versions of Enterprise Developer earlier than 2.2 Update 1, with an additional correction relating to Char Varying data items.

The behavior has been restored to that in Enterprise Developer versions earlier than 2.2 where, when compiling with –zp1, all parameters are treated as unaligned. (In Enterprise Developer 2.2 Update 1, the behavior when compiling with –zp1 was to not treat parameters as if unaligned).

When using the –zp1 compiler option, all Character Varying data items are now treated as if unaligned. In previous versions of Open PL/I, for Character Varying data items, the –zp1 unaligned requirement was applied only to structure members and parameters.

To illustrate the change, consider the following example:

zptest: proc options(main);

   dcl 1 st1,
     2 c char,
     2 x(4) char(7) var init ('a', 'xx', 'yyy', 'zzzz');

   dcl y(4) char(7) var init ('a', 'xx', 'yyy', 'zzzz');

   dcl sub entry ((4) char(7) var);

   call sub (x);

   call sub (y);

end;

sub: proc (z);

   dcl z(4) char(7) var;

   dcl i fixed bin(31);

  do i = 1 to hbound(z);
      z(i)  = 'x';
  end;

end;

Where:

  • For x and z, each char (7) var item is 7 plus 2 bytes which equals 9 and then multiplied by 4 equals 36.
  • If y were aligned on half-word by default, each array element is half-word aligned and each equals 10 bytes (9 + 1 pad byte), and the total size equals 40 bytes.
  • At call sub (x), the calling argument and parameter are matched.
  • At the call sub (y), the y element size (10 bytes) is mismatched against the parameter z element size (9 bytes) due to –zp1. This is incorrect and causes unexpected program behavior.

Due to this correction of treating all Char Varying data items as if unaligned when using –zp1, the size of CHAR VARYING arrays now differs from previous versions of Open-PL/I. For example:

   dcl X(4) char(7) var;

   Put skip list (size(X))  /* size is 36 bytes vs. 40 bytes in previous versions of Open-PL1 */
  • Intel-Specific Options
Parent topic: Compiling a Program
Related information
Optimization
The -exp Option
The -l Option
The -map Option
External Names
Open PL/I Compiler Diagnostic Messages
Compilation Statistics
Structure


Intel-Specific Options

The Intel-specific options and their default settings are listed below. Use the default settings of the Compiler options to generate the most efficient code for your system.

-codealign argument
Controls alignment of the generated code where argument is a concatenation of one or more of the following suboptions. Note that each suboption must be followed by a number that is one of 4, 8, or 16; this subargument is referred to as align in the descriptions.
j | Align each label that follows an unconditional jump or a return to be at an address such that mod(address, align)=0. The NOPs that are inserted are never executed.
e | Align each entry point such that mod(address, align)=0.
I | Align loop tops such that mod(address, align)=0.
h | Use heuristics to attempt to align labels that do not follow jumps such that mod(address, align)=0, but without inserting any NOP instructions. If align is followed by ".1", alignment will be such that mod(address, align)=0 or 1. The suboptions tell the Compiler where to insert NOP instructions to force the address of critical instructions in generated code to be aligned on boundaries that improve the performance of jumps and calls to those instructions.
-f287
Generates Intel287 floating-point coprocessor instructions where possible. This is the default if an Intel387 coprocessor is not present.
-f387
Generates Intel387 floating-point coprocessor instructions where possible. This is the default if an Intel 80387 coprocessor is present. If an Intel387 coprocessor is not present, the default generates Intel287 floating-point instructions.
-i386
Produces code for the Intel386 processor avoiding optimizations designed for the Intel486 processor. Programs compiled with the -i386 option run correctly on the Intel486, but may perform better when they are compiled with the -i486 option. -i386 is the default when the Compiler is run on an Intel386 processor.
-i486
Produces code for the Intel486 processor, using optimizations designed for the Intel486. Programs compiled with the -i486 option may not run on an Intel386 processor. -i486 is the default when the Compiler is run on an Intel486 processor.
-ix86
Produces code that will run well on both the Intel486 and the Pentium CPUs.
-Pentium
Produces code for the Pentium processor. This is the default when the Compiler is run on a Pentium processor.
Parent topic: Compiler Options


Compiler Listings

The Compiler listing options are:

  • -l (list)
  • -map (storage allocation map)
  • -xref (cross-reference)
  • -exp (expanded code)

All listing information is directed to the listing file. When any of the listing options are specified, the -l option is invoked by default.

  • The -l Option
  • The -map Option
  • The -xref Option
  • The -exp Option
Parent topic: Compiling a Program


The -l Option

The -l option produces a listing file, which is named by default with the source program name (up to but not including the last ".") and the suffix .list. You can choose another name for the listing file by specifying a name after the -l option, in the following format:

-l file

The listing file contains a program listing, which consists of a copy of the source program with line numbers beginning at 1 in a column to the left of the source line.

Parent topic: Compiler Listings


The -map Option

The -map option produces a storage allocation map, which displays the location and allocation size of each program entity. The map categorizes this information by name, class, size, location, and attributes.

This information is presented in five columns:

Column | Description
NAME | Indicates the name of each entity in the program.
CLASS | Indicates the storage class of each program entity; for example, AUTOMATIC, CONSTANT, STATIC, PARAMETER, CONTROLLED, or BASED.
SIZE | Indicates the size of the entity, usually in bytes. If the size is measured in bits, the size number is followed by a B. If the size of the entity is not constant, a -V- is displayed in the location listing. Entities of class ENTRY or BUILTIN have no size or location listing.
LOCATION Gives the offset location of the entity in hexadecimal notation.
  • For automatic variables, the location column gives the memory offset from the frame pointer
  • For static variables, it gives the memory offset from the beginning of static data
  • For controlled and based variables, it displays the value -V-
ATTRIBUTES Displays the data type of the entity, for example, FIXED DEC, FLOAT BIN, CHAR, CHAR VAR, BIT ALIGNED, and ENTRY.

Displays BUILTIN for an entity of BUILTIN class. Displays the precision and scale of the entity, where applicable, in parentheses: for example, FIXED BIN(15,0).

Program entities are listed in the order in which they appear in the procedure.

The map first lists external entry points to the program: external constants, subroutines, or programs, including the source program itself. These entry points are listed with name, class, and attributes.

The map then lists program procedures and entities by line number.

Parent topic: Compiler Listings


The -xref Option

The -xref option provides cross-reference information for each program entity, displaying the line number on which it was declared and the line numbers of all references to it.

The -xref listing for a program is added to the map listing; when you specify the -xref option, you receive a data storage allocation map by default. The cross-reference information appears on the map in the ATTRIBUTES column for each entity, after the line of map attributes information.

References to each entity are listed in the following format:

 DEF line_number REF line_number[...]

A sample map listing with the -xref option follows.

Figure 1-1 Sample Output from the -xref Option

EXTERNAL ENTRY POINTS
NAME         CLASS           SIZE  LOCATION  ATTRIBUTES
SYSPRINT     CONSTANT                        FILE EXTERNAL
                                             DEF 41 REF 41 48 49
PRIMES       CONSTANT                        ENTRY(MAIN)EXTERNAL
PROCEDURE PRIMES ON LINE 10
NAME         CLASS           SIZE  LOCATION  ATTRIBUTES
STORE_CLASS  CONSTANT                        ENTRY
                                             DEF 90 REF 45
ARITH_STR    CONSTANT                        ENTRY
                                             DEF 56 REF 43
PROCEDURE ARITH_STR ON LINE 56
NAME         CLASS           SIZE  LOCATION  ATTRIBUTES
DECIMAL      BUILTIN                   BUILTIN
ESC          AUTOMATIC 6     FFFFFFD8  PICTURED
FLT_BIN      AUTOMATIC 4     FFFFFFE4  FLOAT BIN(15)
                                       DEF 63 REF 71
FIX_DEC      AUTOMATIC 3     FFFFFFEC  FIXED DEC(4,2)
                                       DEF 62 REF 70
CHR_STR      AUTOMATIC 4     FFFFFFEO  CHAR(4)
                                       DEF 61 REF 69
BIT_STR      AUTOMATIC 4B    FFFFFFD4  BIT(4)
                                       DEF 60 REF 68
PROCEDURE STORE_CLASS ON LINE 90
NAME         CLASS     SIZE  LOCATION  ATTRIBUTES
NUMBER       AUTOMATIC 16B   FFFFFFE8  UNION
 FIXED_N     MEMBER    2     00000000  FIXED BIN(15,0)
 FIXED_N_BIT MEMBER    16B   00000000  BIT(16)
STAT_A_EX    STATIC    3     External  FIXED DEC(5,0)EXTERNAL
Y            BASED     4     -V-       FLOAT BIN(23)
Parent topic: Compiler Listings


The -exp Option

The -exp option produces an expanded code listing at the end of the listing file, providing the location and low-level language translation for each instruction and label in the program. The following information is displayed for each statement, in five columns:

Column | Displays
First | The source statement line number.
Second | The offset location of each instruction in the statement.
Third | The hexadecimal representation of each instruction.
Fourth | The instruction in a pseudo-assembly code dialect.
Fifth | Information about the operands used by each instruction.
Parent topic: Compiler Listings


Open PL/I Compiler Implementation Limits

The Compiler generates messages if your source program exceeds certain Open PL/I Compiler implementation limits. The following table lists these implementation limits.

Message | Limit
Depth of nesting of a structure | 16
Maximum length of an ‘external’ string constant | 30721
Maximum length of an ‘internal ’ string constant | 327672
Maximum length of a string constant with repeat specifier | 32767
Maximum length of source line | 1024
Maximum length of an identifier | 100
Maximum size of storage for AREA data | 2GB Note: Very Large area sizes may be impacted by system resources.
Array dimensions | 8
Nesting level of INCLUDE statements | 7
Nesting of DO, PROCEDURE, BEGIN, SELECT, and simple ON-unit statements | 643
Number of arguments in a subroutine or function call | 239
Number of data and format list pairs in an edit-directed specification | 256
Number of diagnostics (see the -maxmsg option in Compiler Options for information on configuring this limit.) | 1000
Maximum VSAM key size | 120 bytes
Scale factor of variables | 0 ? scale factor ? 128
Scale factor of a constant | 0 ? scale factor ? 127
Scale factor of a conversion built-in function | 0 ? scale factor ? 127
Value of a format's repeat, w, or d field | 254
Precision for a fixed binary number | 31
Precision for a fixed decimal number (maximum) | 31
Precision for a float binary number | 52
Precision for a float decimal number | 16
Internal Limits |
Number of tokens in a statement | 20,000
Parent topic: Compiling a Program
Related information
Compiler Options
1

The spelling of an external string constant (as presented in the user program) is limited to 3072 characters, where the spelling includes the surrounding quotation marks, the extra quotation mark when two single quotation marks represent a single quotation mark inside the string, and the possible combination of postfix characters such as B or X.

2

The internal spelling of a character string constant (i.e., a compiler generated string constant as the result of Restricted Expression Evaluation) of is limited to 32767 characters, where the spelling includes the surrounding quotation marks.

3

64 including the top level procedure.


Open PL/I Compiler restrictions

  • The compiler does not diagnose the use of uninitialized automatic variables in the procedure block prolog.
  • The compiler does not detect dependencies in order of evaluation of automatic variables in the procedure block prolog nor does it diagnose those dependencies.
Parent topic: Compiling a Program


Compilation Statistics

The -stat compiler option provides a listing of statistics for each phase of the compilation. The statistics are displayed at the terminal by default or can be redirected to a file. The following figure is a sample terminal display from a UNIX system.

Figure 1-2 Sample Output from the -stat Option (UNIX)

PHASE            USER     SYSTEM    CPU  REAL  13:43:26
Parser Pass 1    0.05       0.02   0.07     0  13:43:26
Declare          0.00       0.00   0.00     0  13:43:26
Parser Pass 2    0.08       0.03   0.11     0  13:43:26
Allocator        0.01       0.00   0.01     0  13:43:27
Code Generator   0.71       0.05   0.76     1  13:43:27
Total            0.85       0.10   0.95     1  13:43:27

Total source lines:                  38
Lines per minute (CPU):           2,400
Lines per minute (real):          2,280

Text size:                 2,574 bytes
Data size:                   914 bytes
Bss Size:                      0 bytes

The following names and describes each of the columns displayed in the printout.

Column | Description
PHASE | Defines the various phases of the compilation. Each phase and its corresponding statistics displays upon completion.
USER | Indicates the CPU time spent on this phase of compilation, excluding CPU time spent by the operating system on behalf of the Compiler.
SYSTEM | Indicates the CPU time used by the operating system while executing the corresponding phase.
CPU | Indicates the CPU time used by the Compiler while executing the corresponding phase. This is simply the sum of USER and SYSTEM.
REAL | Indicates the number of seconds elapsed during the corresponding phase.
The final column | Displays the current time of day in 24-hour notation (on Intel systems only).
Parent topic: Compiling a Program


Temporary Files

Compiler-generated temporary files are normally placed in the /tmp directory. If you wish to put them in your current working directory, use the command appropriate to your shell program.

Bourne/Korn shell users: | TMPDIR=. ; export TMPDIR
C shell users: | setenv TMPDIR .

To store Compiler-generated temporary files elsewhere, specify a pathname by using the command appropriate to your shell program.

Bourne/Korn shell users: | TMPDIR=pathname; export TMPDIR
C shell users: | setenv TMPDIR pathname
Windows users: | set TMPDIR=pathname
Parent topic: Compiling a Program


Optimization

By default, programs are not optimized during compilation. You can specify optimization at level 1, 2, or 3, using the following syntax:

-opt level

For example, "-opt 2". If you specify -opt with no level, level 3 optimizations are performed by default. (Remember that if you use the -deb option, only level 1 or 2 is allowed. If you use -deb and specify -opt with no level, level 2 optimizations are performed.) A brief description of the optimizations performed at each level follows.

Level | Description
1 | Operator pattern replacement and Boolean conditional expression optimizations.
2 | Common subexpression elimination; all level 1 optimizations.
3 All level 1 and level 2 optimizations plus the following:
  • branch chaining
  • dead code elimination
  • strength reduction
  • loop induction
  • loop invariant code motion
  • removal of redundant register saves and loads
  • removal of mathematical identities
  • peephole optimizations
  • constant folding
Parent topic: Compiling a Program


Linking a Program

Attention: You must recompile and relink your Open PL/I applications to use them with this Enterprise Developer release.

You can use either static or dynamic linking of Open PL/I applications. The Open PL/I run-time library is built as a static library (.lib). The ldpli link-step uses the static version of the Open PL/I run-time library by default. To link, use

ldpli -dll [options…]

You also need to add to the command one of the options below:

  • -mvs - for programs executed under the control of JCL.
    Note: -mvs is deprecated and will be removed in a future release. Please use the -systemmvs option instead.
  • -ims - for programs executed under the control of IMS.
    Note: -ims is deprecated and will be removed in a future release. Please use the -systemmims option instead.
  • -cics - for programs executed under the control of CICS.
  • -db2 - for programs executed under the control of DB2.
    Note: This option is required for the mfdb2 preprocessor, which is deprecated. Please use the EXEC preprocessor (invoked by -sql db2).

To link an Open PL/I program, use either mfplx or ldpli.

  • mfplx compiles and links in one step, automatically invoking ldpli if the -c option is not used. For the use of mfplx, see the section mfplx Syntax .
  • ldpli references the components that were installed with this version of Open PL/I and is the recommended link command when using mfpli.
  • Link Options
  • Using ldpli
Parent topic: Using Open PL/I
Related information
mfplx Syntax


Link Options

The table below lists link options that permit the use of Open PL/I with other software products. For more information, see the section Using Open PL/I with Other Software Products.

Option | Explanation
-mvs | Allows linking of programs running under the control of JCL. Note: -mvs is deprecated and will be removed in a future release. Please use the -systemmvs option instead.
-ims | Allows linking of programs running under the control of IMS. Note: -ims is deprecated and will be removed in a future release. Please use the -systemmims option instead.
-cics | Allows linking of programs running under the control of CICS.
-db2 | This option is required for the mfdb2 preprocessor, which is deprecated. Please use the EXEC preprocessor (invoked by -sql db2).
-systemcics | Compiles and/or links to execute under CICS.
-systemims | Compiles and/or links to execute under IMS.
-systemmvs | Compiles and/or links to execute under MVS.
-dll | Generates a dynamically linked library.
-so | Generates a shared object.
-strip | Tells ldpli to strip the debugging information.
-nostrip | Tells ldpli to not strip the debugging information. This is the default.
-o | Specifies executable file name.
-L | Specifies library search path.
-l | Specifies library.
-Q [option] | Specifies nativeld options.
-verbose/-stat | Prints information/statistics to the standard output as each linker phase completes.
-version/-v | Shows the version number of the linker.
-fixedvalidate | Causes the RTS to turn on additional checking to ensure that FIXED DECIMAL field contents are can contain characters 0 through 9 and CDF hex values. This option raises the CONVERSION condition if the assignment or the result of a math operation causes the FIXED DECIMAL field to contains an invalid character. The default is -nofixedvalidate.
-fixedoverflow | Enables checking that raises the SIZE condition if an operation causes a FIXED DECIMAL value to overflow. The default is -nofixedoverflow.
-z | Creates a shared library suitable for use with cob.
Note: System linker options are not accepted directly. They can be added using the -Q option.
Parent topic: Linking a Program
Related information
Using Open PL/I with Other Software Products


Using ldpli

Attention: You must recompile and relink your Open PL/I applications to use them with this Enterprise Developer release.

ldpli references the components, such as libraries, that were installed with Open PL/I. ldpli generates executable files and shared libraries from relocatable object files.

Tip:

The first and fourth characters of the ldpli command are lowercase letter "L".

The ldpli command-line syntax is as follows:

ldpli [option] ... object_file [object_file] ... [optional_library] ...

where

ldpli | The command that invokes the linker.
option | Represents the linker options. To see all valid options enter the ldpli command with no arguments. Note: System linker options are not accepted directly. They can be added using the -Q option.
object_file | Specifies object files that are to be linked.
optional_library | Represents library specifications for libraries that are required for your special application. These are needed only if you explicitly CALL library routines from your program. The standard system libraries, such as libc.a on a UNIX system, are always included in the link.
Note: If linking using your own shell scripts and/or driving ld directly, you must change from using -lmf to use -lmfpliz (PL/I in Enterprise Developer) or -lmfpli (Open PL/I). libespli.so and libespliz.so are no longer used.
  • Using ldpli with Windows Systems
Parent topic: Linking a Program


Using ldpli with Windows Systems

In addition to supporting all LINK32 options, ldpli includes the following support for Windows systems:

  • Indirect files (@ files).
  • The -# option, which echoes the command line used to invoke LINK32. This can also be used to redirect output for later use in indirect files.

ldpli enhances the default behavior of the following LINK32 options:

  • If -out:filename is not specified, ldpli will generate an executable file with an extension .exe using the basename of the first object file rather than defaulting to noname.exe.
  • If -map is specified without specifying the filename (-map:filename), ldpli will generate a map file with the extension .map using the basename of the first object file.
Note: If linking using your own shell scripts and/or driving ld directly, you must change from using -lmf to use -lmfpliz (PL/I in Enterprise Developer) or -lmfpli (Open PL/I). libespli.so and libespliz.so are no longer used.
Parent topic: Using ldpli


Running a Program

To run an Open PL/I program, invoke the executable object file produced by the link utility.

The name of the executable object file produced by the linker defaults to a.out. However, if you include the -o filename option on the link command line, the executable object file has the filename that you specified.

For example, "-o sample" on the mfplx command line produces an executable object file named "sample".

  • Run-time Errors
  • Accessing Command-Line Arguments in Open PL/I Programs
  • Associating a Logical Open PL/I File with a Physical Disk Data File
  • Creating a DLL
Parent topic: Using Open PL/I


Run-time Errors

If an error occurs at run time, a message appears on the terminal.

You can use Open PL/I's ON statement to develop handlers for the conditions that can occur in your program. The ON ERROR statement can be used for arbitrary errors. The ONLOC built-in function can be used in an ON-unit to report the name of an entry in which a condition was raised, and the ONCODE built-in function can be used to report the status value of a run-time error.

Note:

If an error is not caught by an ON-unit, Open PL/I displays the source file and line number where the error occurred. For these features to work, however, you must have compiled the source file with the default option -unixdebug.

This feature is currently available only in the Sun Solaris 2 and IBM AIX versions of Open PL/I.

When a fatal error condition occurs at run time, a message is displayed naming the condition that has been raised; the program address where this occurred; and the source file, entry, and line number at which the condition was raised, as well as the lines in each procedure above it in the call stack. For example:

*** Condition ERROR raised
***Unhandled condition ZERODIVIDE at PC=00010233
CALCDIV line 26 in /dirl/dir2/calcs.pl1
SUBR3 line 444 in /dirl/dir2/subprog.pl1
MYPROG line 871 in /dirl/dir2/mainprog.pl1

In this example,

CALCDIV | Is the entry in which the "ZERODIVIDE" condition was raised.
SUBR3 | Is the entry that called "CALCDIV" (at line 444).
MYPROG | Is the program that called SUBR3.

If you have compiled your program using the -nounixdebug option, only the program address where the condition was raised will be displayed:

*** Condition ERROR raised
*** Unhandled condition ZERODIVIDE at PC=00010233
Parent topic: Running a Program
Related information
Open PL/I Run-time Error Messages


Accessing Command-Line Arguments in Open PL/I Programs

It is sometimes useful to be able to execute a program specifying one or more arguments on the command line in order to cause a variation in the program's behavior. For example, to run a departmental expense report program, you might issue the command deptexp summary to indicate that you wish to see only category totals rather than all the line items.

Command-line arguments can be accessed in a PL/I main program using the following technique:

/* PL/I main program accessing command line args. */

PMAIN: PROCEDURE OPTIONS(MAIN);

   dcl getargc entry() returns(fixed bin(31)) external('__lpi_get_argc' );
   dcl getargv entry() returns(pointer) external('__lpi_get_argv' );
   DECLARE ARGC_     FIXED BIN(31) NATIVE init(getargc());
   DECLARE ARGV_     POINTER              init(getargv());
   DECLARE ARG(10)   POINTER BASED;
   DECLARE ARGS      CHAR(50) BASED;
   DECLARE ARGSV     CHAR(50) VARYING;
   DECLARE I         FIXED BIN(31);

   PUT SKIP EDIT(ARGC_)(f(2));
   DO I = 1 TO ARGC_;
      ARGSV = SUBSTR(ARGV_->ARG(I)->ARGS,1,
            INDEX(ARGV_->ARG(I)->ARGS,BYTE(0))-1);
      PUT SKIP EDIT('"',argsv,'"')(a,a,a);
      END;
   PUT SKIP;

   END PMAIN;

If your PL/I program is controlled by a C main program, you can pass the command-line arguments through to the PL/I program in the following manner:

/* C main program calling PL/I subroutine */

main(argc,argv)
   int argc;
   char **argv;
{
   PSUBR(argc,argv);
}

/* PL/I subroutine receiving command line args
   from C main program */

PSUBR: PROCEDURE(ARGC,ARGV);

   DECLARE ARGC      FIXED BIN(31) VALUE;
   DECLARE ARGV      POINTER VALUE;
   DECLARE ARG(10)   POINTER BASED;
   DECLARE ARGS      CHAR(50) BASED;
   DECLARE ARGSV     CHAR(50) VARYING;
   DECLARE I         FIXED BIN(31);

   PUT SKIP EDIT(ARGC)(f(2));
   DO I = 1 TO ARGC;
      ARGSV = SUBSTR(ARGV->ARG(I)->ARGS,1,
            INDEX(ARGV->ARG(I)->ARGS,BYTE(0)));
      PUT SKIP EDIT('"',ARGSV,'"')(a,a,a);
      END;
   PUT SKIP;

END PSUBR;
Parent topic: Running a Program


Associating a Logical Open PL/I File with a Physical Disk Data File

Open PL/I supports a number of ways to associate your physical disk data files with the logical file names used in Open PL/I sources.

  • Method 1 (Default)
  • Method 2
  • Method 3
Parent topic: Running a Program


Method 1 (Default)

The run-time environment will use the name of the file variable (or constant) used in the source, shifted to all uppercase.

Example

dcl Payroll file input;
open file(Payroll);

A file named PAYROLL will be used for all I/O operations using file Payroll.

Parent topic: Associating a Logical Open PL/I File with a Physical Disk Data File


Method 2

Using the TITLE option on the OPEN statement allows one to specify an explicit disk file name with an optional directory prefix. The use of the TITLE option takes precedence over method 1.

Example

dcl Payroll file input;
open file(Payroll) title ('/global/acct/sep-95.days')

A file named /global/acct/sep-95.days will be used for all I/O operations using file Payroll.

dcl Payroll file input;
dcl filename character(100) varying;
<assignment into filename>
open file(Payroll) title (filename);
                                   /* Using a variable name */

The value of filename determines the file that will be used for all I/O operations using file Payroll.

Note:

Once the file has been opened, changing the value of filename will have no impact. The association is made only once, at the time of the open.

Parent topic: Associating a Logical Open PL/I File with a Physical Disk Data File


Method 3

The physical disk file name can be specified with the use of UNIX shell environment variables. This method takes precedence over methods 1 and 2. This method allows you to easily alter the physical disk file used for different invocations of the same application.

The environment variable name is the value of the derived name from either of the above methods with MF_ or DD_ prefixed.

Example

dcl file data2 update;
dcl file specs output;

open file (data2);
open file (specs) title('report');

By setting the following environment variables:

  • setenv MF_DATA2 /common/data
  • setenv MF_REPORT /common/report

I/O operations for file data2 will access /common/data and I/O for file specs will access /common/report.

Note that to override the name for file variable "specs", the name MF_REPORT was used, because of the title option on its OPEN statement.

In the above example, environment variables of the names DD_DATA2 and DD_report would also be allowed.

Note:

To assign a physical file to the following special file declarations you will need to use the corresponding environment variables:

SYSIN | use DD_STDIN
SYSPRINT | use DD_STDOUT
SYSOUT | use DD_STDOUT
Parent topic: Associating a Logical Open PL/I File with a Physical Disk Data File


Creating a DLL

To create a .dll, you need to compile and link one or more object files. This is done by using the command below:

mfplx newdll.pli  -defext -dll

In this example, newdll.pli is your source file. You compile and link it in one step with the command-line driver mfplx.

-defext causes external variables to be defined in the .data section. You must use the link option -dll to create a .dll.

You also need to add to the command one of the options below:

  • -mvs - for programs executed under the control of JCL.
  • -ims - for programs executed under the control of IMS.
  • -cics - for programs executed under the control of CICS.
  • -db2 - for programs executed under the control of DB2.
Parent topic: Running a Program


Program Debugging

  • Using PLIDUMP
  • Debugging CICS Applications with EXEC CICS LINK Statements
    Describes how to PL/I that calls a CICS program using EXEC CICS LINK.
  • PL/I Debugging in JCL and IMS
    Provides a debugging strategy for programs JCL- or IMS-based programs in PL/I
Parent topic: Using Open PL/I


Using PLIDUMP

This section describes dump options and syntax used to call PLIDUMP, and describes PL/I-specific information included in the dump that can help you debug your programs.

This shows an example of a PL/I routine calling PLIDUMP to produce a Program Environment dump. In this example, the main routine PLIDMP calls PLIDMPA, which then calls PLIDMPB. The call to PLIDUMP is made in routine PLIDMPB.

%PROCESS MAP GOSTMT SOURCE STG LIST OFFSET LC(101);
 PLIDMP: PROC OPTIONS(MAIN) ;

   Declare   (H,I) Fixed bin(31) Auto;
   Declare   Names Char(17) Static init('Bob Teri Bo Jason');
   H = 5;	 I = 9;
   Put skip list('PLIDMP Starting');
   Call PLIDMPA;

     PLIDMPA:  PROC;
       Declare (a,b) Fixed bin(31) Auto;
       a = 1;	 b = 3;
       Put skip list('PLIDMPA Starting');
       Call PLIDMPB;

         PLIDMPB:  PROC;
           Declare  1 Name auto,
             2 First   Char(12) Varying,
             2 Last    Char(12) Varying;
           First = 'John';
           Last = 'Thompson';
           Put skip list('PLIDMPB Starting');
           Call PLIDUMP('TBFC','PLIDUMP called from procedure PLIDMPB');
           Put Data;
         End PLIDMPB;
     End PLIDMPA;
 End PLIDMP;

This example is referenced throughout this section.

Consider the following when using PLIDUMP:

  • Use a unique user-identifier for each PLIDUMP invocation when calling PLIDUMP a number of times in a routine. This simplifies identifying the beginning of each dump.
  • A DD statement with the ddname PLIDUMP can be used to define the data set for the dump. Any data set defined by these DD statements should specify a logical record length (LRECL) of at least 300/304 to prevent dump records from wrapping. If using SYSOUT as the target in any of these DDs, specify MSGFILE(SYSOUT,FBA,300,0) or MSGFILE(SYSOUT,VBA,304,0) to prevent line wrapping.
  • If you want the program unit name, program unit address, and program unit offset listed correctly in the dump traceback table, compile your PL/I program with the -debug option. The -debug option can be used with the -opt or -opt3 options. To get symbols and line information in the dump, you must compile using the -debug option to generate the .stb files.
  • Generated .stb files should either be stored in the same location as the .exe, .dll or .so files. or in a location specified by the environment variable CODEWATCH_STBPATH. Otherwise the dump generated by PLIDUMP contains much less useful information.
  • On Windows platforms, an additional .pdb file must also be stored in one of the concatenated directories referenced by the CODEWATCH_STBPATH environment variable or stored in the same location as the .dll it is associated with. Otherwise a S0C4 abend may occur while trying to process the call stack when running under Enterprise Server.

Using PLIDUMP to generate a dump of your PL/I routine helps to ensure portability across system platforms.

  • Finding Variables in PLIDUMP Output
Parent topic: Program Debugging


Finding Variables in PLIDUMP Output

Compile your program with the MAP option to find variables in the PLIDUMP output. The MAP option tells the compiler to add a table to the listing that shows the offset within AUTOMATIC and STATIC storage of all level-1 variables that are AUTOMATIC or STATIC.

  • Finding AUTOMATIC Variables
Parent topic: Using PLIDUMP


Finding AUTOMATIC Variables

AUTOMATIC variables automatically display in the dump. You do not need to find offsets within automatic using the output from the MAP option.

STATIC and CONTROLLED variables are currently not used.

Parent topic: Finding Variables in PLIDUMP Output


Debugging CICS Applications with EXEC CICS LINK Statements

Use this command in the PL/I debugger before the LINK statement runs to debug called programs in code when the EXEC CICS LINK statement is used.

shlib [pgm].dll

where [pgm] is the name of the program executed with EXEC CICS LINK.

Executing this command before the LINK statement runs raises a load event (signal #6) when the program loads prior to execution.

This program contains a link to the program PGMB using EXEC CICS LINK.

PGMA: proc(comm_ptr) options(main,reentrant) reorder;
  dcl comm_ptr pointer;
  dcl data_lngth        fixed bin(15) init(100);
  dcl commarea char(100) based(comm_ptr);

  if eibcalen = 0 then
    do;
      alloc commarea set(comm_ptr);
      commarea = '%from pgma';
    end;
  else;

  exec cics link
      program('pgmb ')
      commarea(commarea)
      length(data_lngth);

  free commarea;

  exec cics return;
end;

In this sample, executing the command shlib pgmb.dll before the LINK statement runs causes the debug session to raise the load event before the program loads. Once the load event is received, executing the ENV command (in this case ENV pgmb) to the new program allows you to then set one or more breakpoints before continuing execution. Note that shlib works on the filename level, so the file extension is required in the command.

Parent topic: Program Debugging


PL/I Debugging in JCL and IMS

PL/I programs containing EXEC SQL, EXEC CICS, or EXEC DLI statements can use the preprocessor -optexec option with the plitest parameter. This causes the preprocessor to inject a PL/I macro into the code. The macro invokes the debugger through an infused PLITEST() call. This is done automatically and does not require editing a side file such as PLIDEBUG.DAT. It also does not require knowledge of explicit CodeWatch commands.

However, this debugging method cannot be used for batch programs that do not have EXEC language capability, or for IMS-based programs that use PLITDLI instead of EXEC DLI.

For these types of programs, you can use a technique similar to that used by the EXEC preprocessor, but in the PL/I Macro preprocessor, to automatically generate a PLITEST() call.

  1. Put the following code anywhere within the execution path of the program to be debugged:
    %if ATTACHDEBUGGER %then
%do;
    DCL JAVAUI FIXED BIN(31) NATIVE VALUE(1);
    CALL PLITEST("shlib " || procedurename() || ".dll;" ||
                 "env "   || procedurename() || ";br STARTDEBUG;" ||
                 "br %exit [det;q];c",
                 " ", JAVAUI);
    STARTDEBUG:;
%end;

    This code causes a debugger to automatically attach itself during program execution, and stop on the STARTDEBUG label.

    Note: The above code assumes a Windows environment with the assumption that a .DLL is being used.. It uses the PL/I built-in function PROCEDURENAME() to dynamically determine the environment and the shlib argument.
  2. If compiling the program from the command line, add the following options to the mfplx command (or just the -define option if invoking mfpp explicitly):
    –deb -macro -define attachdebugger
  3. Start the Enterprise Server and execute the program.
    Note: If working in a Windows environment, the Enterprise Server must be started from an Enterprise Developer command prompt using casstart, or the debugger won't be attached.

In the code sample, the %if..%do condition is functionally similar to $IF in COBOL or #ifdef in C. The sample as a whole is a functional equivalent to CBL_DEBUGBREAK, with the added capability of being ably to specify any additional CodeWatch commands, such as setting breakpoints, to be executed upon startup.

Parent topic: Program Debugging


Using Open PL/I with Other Software Products

Because Open PL/I supports a wide range of data types and because it supports standard calling sequences, Open PL/I can be used with many other software products. These include other Micro Focus products as well as products from other companies. This section lists some of the products that Open PL/I is known to work with and gives some hints about using them with Open PL/I.

  • Open PL/I Migration Issues and Restrictions
    Lists migration issues related to Open PL/I
  • DB2
  • C++/Views
  • Open PL/I and Informix
  • Open PL/I and Micro Focus
  • Open PL/I and IBM WebSphere MQ
Parent topic: Using Open PL/I


Open PL/I Migration Issues and Restrictions

These are issues related to migrating Open PL/I programs to PL/I in Enterprise Developer.

  • If you are using DSNTIAR or DSNTIAC APIs, you must delete declarations (DECLARE) of any entry point(s).
  • DB2 LUW does not support ROWSET operations.
  • Because DB2 LUW does not support arrays, the DB2 LUW ECM also does not support arrays. As a result, MFEXECPP can stop responding if it attempts to use a host variable that is an array of structures.
  • As PL/I projects only compile for x86 platforms, some of the upgraded projects might target unsupported platforms and might not be configured to build. You must open the solution properties and, on the Configuration Properties, ensure all projects are set to build and set their target platform to x86.
Parent topic: Using Open PL/I with Other Software Products


DB2

Open PL/I can be used with the IBM's DB2 database system. Open PL/I has a preprocessor for embedded EXEC SQL statements in your PL/I programs, and a DB2 LUW preprocessor used by COBOL applications that is based on the HCO for DB2 LUW preprocessor.

Note:

Since the HCO for DB2 LUW preprocessor must connect to the DB2 LUW server to convert EXEC SQL statements to API calls, you must use the DB option for PL/I when building applications using SQL. Invoke the DB2 LUW preprocessor with the -db2 option to the mfplx command.

Open PL/I's DB2 support is license managed. You must obtain a special license from Micro Focus to use it.

You must also have IBM's DB2 product, or the IBM DB2 LUW DS Client V9.5 or later, and your system path must be set to the include the install product location.

Parent topic: Using Open PL/I with Other Software Products
Related information
Precompiler and Preprocessor Order of Execution
Open PL/I SQL Options


C++/Views

C++/Views is Intersolv's object-oriented graphical user interface (GUI) program framework. C++/Views includes an interactive graphical designer, as well as an extensive C++ class library. Using C++/Views, you can create the framework for an application with an attractive and efficient graphical user interface. Your C++ framework can then call procedures written with Open PL/I to do your ordinary data processing work.

C++/Views is not yet available on the following platform supported by Open PL/I:

  • Intel-based computers running UNIX SVR4 or Windows
Parent topic: Using Open PL/I with Other Software Products


Open PL/I and Informix

Open PL/I follows the native C compiler's naming conventions. This allows you to mix subroutines and functions compiled with Open PL/I with any other language or third-party library that supports a C language interface. However, you must link the Open PL/I run-time libraries into the final stand-alone program. The -cisam link option enables the C-ISAM package from Informix for VSAM/indexed files.

Informix fully documents their Application Programming Interface for the C language. In general, you should follow the Informix directions for mixing Informix and C, simply treating the modules compiled with Open PL/I as C modules.

The following examples illustrate the command used to link an Open PL/I program that uses the Informix libraries. For the purposes of this illustration the Open PL/I Compiler and Informix modules are running on a Sun Solaris system. The Open PL/I modules are called "testobj1.o" and "testobj 2.o", the Open PL/I Compiler has been installed in /opt /pl1, and the environment variable $MFPLI_PRODUCT_DIR has been set to that directory.

ldpli testobj1.o testobj2.o -o testprogram
/opt/informix/lib/esql/libsql.a
/opt/informix/lib/esql/libgen.a
/opt/informix/lib/esql/libos.a
/usr/ucblib/libucb.a
/opt/SUNWspro/SC3.0/lib/cg92/_fstd.o

Note that the names and locations of the Open PL/I and Informix libraries are specific to your installation of Informix and Open PL/I. This illustrates a typical installation.

Parent topic: Using Open PL/I with Other Software Products
Related information
Language Concepts


Open PL/I and Micro Focus

Open PL/I follows the native C compiler's naming conventions. This allows you to mix subroutines and functions compiled with Open PL/I with any other language or third party library that supports a C language interface. You must link the Open PL/I run-time libraries into the final stand-alone program. Micro Focus fully documents inter-language calling between COBOL/2 and C. In general, you should follow the Micro Focus directions for mixing COBOL and C, simply treating the modules compiled with Open PL/I as C modules. The following test program illustrates a COBOL program that calls a PL/I function, passing a string as an argument.

The COBOL source code module:

WORKING-STORAGE SECTION. 01 STR PIC X(20).
*
PROCEDURE DIVISION.
CALL-PL1 SECTION.
DISPLAY "Calling the PL/I program".
CALL "PL1PROC" USING STR.
DISPLAY "Return from PL/I program".
DISPLAY STR.
STOP RUN.

The PL/I source code module:

PL1PROC: PROCEDURE ( CHARSTR );
DECLARE CHARSTR CHARACTER(20);

CHARSTR = 'This is a real test!';

END PL1PROC;

The commands to compile and link:

mfplx mfpll.pl1 -stat -c

cob mfcob.cbl mfpl1.o -o mf -v -V -x \
    /pl1dir/lib/dflock.o071030 \
    /pl1dir/lib/noofm.o071030\
    /pl1dir/lib/lpi.a071030

Note that the names and locations of the Open PL/I libraries are specific to your version of Open PL/I. This illustrates a typical installation.

Parent topic: Using Open PL/I with Other Software Products


Open PL/I and IBM WebSphere MQ

You can create and run PL/I applications with Enterprise Developer that perform messaging using IBM WebSphere MQ software. The integration must be done on machines that have both Enterprise Developer and IBM WebSphere MQ software installed. See the PL/I tutorials section of the help for more information on installation requirements, supported releases, and using PL/I with IBM WebSphere MQ software.

Parent topic: Using Open PL/I with Other Software Products


Using the PL/I Message User Exit

The PL/I message user exit allows an installation to monitor compile-time and run-time issued messages. Every message that is issued by various PL/I components is presented to the user exit. If it is a compiler-issued message, it is then subjected to the -f compile-time option.

The user exit can:

  • Do nothing and allow the message to be processed by PL/I as is.
  • Change the severity of the message one severity level up or down. Note that I-level (severity level 0) cannot be lowered and U-level (severity level 4) cannot be raised. Thereafter, the message will be issued as is (with the same exact text, including severity level) with a "+" (for raised severity) or "-" (for lowered severity) indication but the new severity will be used for return code purposes.

    Example:

    plisql1.pp (0,0) : Error MPLIE00042W : Errors have ...

    If the severity is lowered, the message will be shown as:

    plisql1.pp (0,0) : Warning MPLIE00042W-: Errors have ...

    The return code will be 4 instead of 8.

    If the severity is raised, the message will be shown as:

    plisql1.pp (0,0) : Severe MPLIE00042W+: Errors have ...

    The return code will be 12 instead of 8.

    Upon return from the exit, the message is not subjected to the -f option. Note the + or - sign that follows MPLIE00042W as this indicates the change in severity.

  • Suppress the message altogether. The severity of the suppressed message still carries through and participates in return code evaluation.
    Important: We strongly recommend that you do not suppress run-time messages.
Note: The user exit API is a trusted interface and is running as part of PL/I and therefore could affect the stability of the run-time system and of the compiler and other components involved.

Enterprise Developer provides a skeleton default user exit that you can modify to suit your needs. It can be used to gather compile-time information for later or real-time analysis. Ensure that your modified user exit either takes precedence over or replaces the provided skeleton user exit.

The compile-time user exit should be built as follows:

  • On Windows:
    mfplx mfplictx.pli -macro -dll -native -opt -nolaxdcl -vax  -sysdef -pp mfplictx.pp”

It must have an executable name of mfplictx (lower case) and be placed in a directory that is on the search path (PATH on Windows).

Parent topic: Using Open PL/I


Compiling, Linking and Debugging of Fetchable Procedures

  • Compiling and Linking of Programs That Are to Be Used As Fetchable Procedures
  • Debugging of Fetchable Procedures
Parent topic: Using Open PL/I


Compiling and Linking of Programs That Are to Be Used As Fetchable Procedures

To compile a program to be used as a fetchable procedure, enter the command:

mfplx -dll -defext myfetch.pli
Note: The compiler options -mvs, -ims, -cics should only be used for the OPTIONS(MAIN) programs. The use of -dll indicates that it is a dynamically linked called subroutine.
Parent topic: Compiling, Linking and Debugging of Fetchable Procedures
Related information
Restrictions


Debugging of Fetchable Procedures

To debug the logic contained within a fetchable procedure you need to use the shlib command to load its symbolic information into the debugger. If you want to stop the debugger just before the invocation of MYFETCH, use the following command:

shlib MYFETCH.dll

As result of this a breakpoint will be set when MYFETCH.dll is loaded and you can then use the env command to switch to the appropriate source code display within MYFETCH.dll and set breakpoints where you think it is appropriate.

If you do not issue the shlib command, the execution will work as expected but you won't be able to debug MYFETCH. Additionally, if a trap occurs within MYFETCH.dll you will not see the source line where the trap occurred but will simply receive a message indicating a hex offset with MYFETCH.

Parent topic: Compiling, Linking and Debugging of Fetchable Procedures


Data File Tools Support for PL/I

Attention: This topic applies to a feature that is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.

The Data File Tools enable you to create record layout and segment layout files using Open PL/I structures. The Data File Editor and IMS Database Editor use these layout files to present records or segments a a formatted data item view that enables easier editing.

When you compile a PL/I program for debug, Enterprise Developer creates an output file containing the PL/I structures that are required as input for the Record Layout Editor and the Segment Layout Editor Data File Tools, which use the information to map PL/I data item types to the COBOL data item types used by the Data File Editor and IMS Database Editor Data File Tools. The output file is added to your Enterprise Developer project, and has a .adt file extension.

  • PL/I to COBOL Data Item Type Mapping
    Describes how the Data File Tools map PL/I data item types to COBOL data item types.
  • Creating and Using a Record Layout File
  • Creating and Using a Segment Layout File
Parent topic: Using Open PL/I


PL/I to COBOL Data Item Type Mapping

Attention: This topic applies to a feature that is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.

PL/I data item types are mapped to COBOL data item types for use within the Data File Editor and IMS Database Editor.

Open PL/I data item type COBOL data item type Comments
char(n)

pic x

Treated as a character string

pic '(n)9'

pic 9  <= 18 digits
pic x   > 18 digits

9 and V symbols are supported

Treated as a character string

 pic '(n)Z9'

pic x

When containing symbols other than 9 and V, treated as a character string

fixed bin(1) - fixed bin(31)

  native1
  non-native

comp-5
comp

PL/I treats length 1 to 6 as length 7

fixed dec(1) - fixed dec(31)

  native
  non-native

comp-3 <= 18 digits
        > 18 digits

Formatted editing allowed

Formatted editing indicates data item contains an illegal value

float bin(1)- float bin(24)

comp-1

Editing disabled for Floating Point

float bin(25) - float bin(52)

comp-2

Editing disabled for Floating Point

float dec(1) - float dec(6)

comp-1

Editing disabled for Floating Point

float dec(7) - float dec(16)

comp-2

Editing disabled for Floating Point

char(n)var

  native1
  non-native

pic x

comp-5 length
comp   length

Treated as a character string plus two bytes for the length preceding the string

widechar(n)

pic x

Treated as a character string of two bytes times n

widechar(n) var

  native1
  non-native

pic x

comp-5 length
comp   length

Treated as a character string of two bytes times n plus two bytes for the length preceding the string

bit(n)

pic x

Bits mapped to the byte(s) that contain them with an indication shown for the bit positions occupied, e.g., (--bbb---)

Note: PL/I bit storage format is either bit swapped or left to right.
pointer

pointer

structure

group item

union

group item
1The native option could present problems for data files that contain comp-5 binary fields. Data File Tools cannot interpret files created on a byte swapped platform that are subsequently moved to a non-byte swapped platform. In this case, where files are used on different byte order platforms, specify the non-native option instead.

Mapping Restrictions

The following Open PL/I data item types are not supported in their original form, but are mapped to a form of COBOL pic x as indicated:

Open PL/I data type item COBOL pic x
char varying

pic x(n +2 for length bytes)
bit

pic x(len/8)

widechar

pic x(n*2)

widechar varying

pic x(n*2 + 2 for length bytes)

The following Open PL/I data item types are not supported:

  • PL/I unique features such as BIT and OFFSET not present in COBOL
  • BASED data items with the REFER option; however, data items up to the first REFER are included in the structure description
  • Arrays of more than three dimensions
  • Arrays with lower bounds of zero or a negative value
Parent topic: Data File Tools Support for PL/I


Creating and Using a Record Layout File

Attention: This topic applies to a feature that is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.

The record layout allows you to edit the records in a data file using the right pane of the Data File Tools window. To create a record layout file:

  1. Right-click on the PL/I program file containing the record data and select Compile to compile it.
  2. Right-click on the PL/I program file containing the record data and select Create Record Layout File to open it in the Layout window. The Data File Tools Layout editor appears with the selected file loaded. The file's data structures display in the left pane, with data from the declarations displaying as separate nodes under the Declarations folder.
    Note: If the character sets used in the Data File Tools editor and the file being opened differ, a message box appears asking if you want to use the character set specified for the file or the character set used in the editor.
  3. To see the record layouts for a given node in the Declarations folder, click and drag the node from the left pane to the right pane. The New Record Layout dialog box appears.
  4. Choose Next, then Finish.
  5. Save the file with the same name as the data (.dat) file, but with a .str extension. So if, for example, the data file is mydata.dat, you must name this file mydata.str in order for the Data File Editor to be able to display the record layout properly.

Loading the record layout in the Data File Editor

Once the .str file is created for a data file, you can view and edit the records in the right pane of the Data File Editor.

  1. In the Solution Explorer, double-click the data file to open it in the Data File Editor.
    Note: The Data File Editor shows the file in the raw display if the .str and .dat names are not the same.
  2. Choose File > Data File Editor > Load record layout.
  3. Select the .str file that was created from the .dat file.

    The file loads in the Data File Editor with the records properly formatted in the right pane.

  4. Edit records as needed. Changes are saved as soon as they are made in the Data File Editor.

For complete information on using these Data File Tools, see Record Layout Editor and Data File Editor.

Parent topic: Data File Tools Support for PL/I


Creating and Using a Segment Layout File

Attention: This topic applies to a feature that is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.

The segment layout allows you to edit the IMS segments in a data file using the right pane of the Data File Tools window. To create a segment layout file:

  1. Right-click on the PL/I program file containing the record data and select Compile to compile it.
  2. Right-click on the PL/I program file containing the record data and select Create Segment Layout File.
  3. Select an IMS database from the list; then click Create to open the layout file in the Layout window. The Data File Tools Layout editor appears with the selected file loaded. The file's data structures display in the left pane, with data from the declarations displaying as separate nodes under the Declarations folder.
    Note: If the character sets used in the Data File Tools editor and the file being opened differ, a message box appears asking if you want to use the character set specified for the file or the character set used in the editor.
  4. To see the segment layouts for a given node in the Declarations folder, click and drag the node from the left pane to the right pane. The New Segment Layout dialog box appears.
  5. Choose Next, then Finish.
  6. Save the file with the same name as the IMS database (.dbd or .psb) file, but with a .slf extension. So if, for example, the database file is mydata.dbd, you must name this file mydata.slf in order for the IMS Database Editor to be able to display the segment layout properly.

Loading a segment layout in the IMS Database Editor

Once the .slf file is created for a database, you can view and edit the segments in the right pane of the IMS Database Editor. If the IMS database file and the segment layout file have the same file prefix name, the IMS Database Editor automatically loads the appropriate segment layout when you start the tool. However, if the filename prefixes do not match, or if you want to apply an alternative segment layout file:

  1. Start the IMS Database Editor.
  2. Choose File > IMS Database Editor > Load Segment Layouts.
  3. Select a .slf file that was created from the database file.

    The file loads in the IMS Database Editor with the segments properly formatted in the right pane.

  4. Edit segments as needed. Changes are saved as soon as they are made.

For complete information on using these Data File Tools, see IMS Segment Layout Editor and IMS Database Editor.

Parent topic: Data File Tools Support for PL/I


EXEC DLI Support in PL/I

PL/I programs that contain EXEC DLI statements can be compiled and executed in the IMS or the CICS environments. EXEC DLI statements are imbedded in user programs much like EXEC CICS statements are. These statements manipulate data in IMS data bases while running under control of IMS or CICS.

The EXEC preprocessor PP support EXEC DLI statements and generates code to execute of these statements.

IMS ECM (imsecm), distinguishes between PL/I and COBOL source code to support EXEC DLI statements in the source code of either language. The EXEC DLI support fully recognizes PL/I variable names, and expressions that contain dashes as well as other PL/I elements as syntactical units.

In Enterprise Developer, you can specify DLI preprocessor options as you would with other preprocessor options.

Parent topic: Using Open PL/I


Language Concepts

This chapter describes the Open PL/I language implementation for your system. For detailed information on the Open PL/I programming language, see your Open PL/I Language Reference Manual.
  • Line Boundaries
  • Main Procedure
  • Data Types
  • Arithmetic Precision
  • External Procedures
  • Maximum Number of Arguments for a Function or Subroutine Call
  • Open PL/I Calling Conventions
  • Special Programming Tasks
    Describes other useful PL/I programming tasks
  • CBL_GET_PROGRAM_INFO (PL/I)
    Returns information for a named program, or a program in the current call stack.
Parent topic: Open PL/I User's Guide


Line Boundaries

A line boundary consists of a new-line character (CRLF on a Windows system), and the line boundary in a quoted string constant is considered part of the string constant.

Parent topic: Language Concepts


Main Procedure

Exactly one of the external procedures that is linked into an executable file must specify the main entry point to the program by including the OPTIONS(MAIN) clause on the PROCEDURE statement. This designates that procedure as the main entry point at which execution should begin, after some run-time initialization has been completed. This option must appear even if the entire program is a single procedure contained in a single source file. Failure to specify a main program, or specifying more than one main program, will cause errors to occur during program linkage.

The main procedure is not required to be a PL/I procedure; that is, it can be written in another language.

Parent topic: Language Concepts


Data Types

The table below lists the Open PL/I data types, along with the alignment and size of their machine representations.

Alignment is the same for Intel, RS/6000, and Sun SPARC, unless otherwise specified.

Data Type | Size | Alignment: aligned data | Alignment: unaligned data
Fixed Binary ( p <= 7) 1 | 1 byte | 1 byte | byte
Fixed Binary (8 <= p <= 15) | 2 bytes | 2 bytes | byte
Fixed Binary (16 <= p <= 31) | 4 bytes | 4 bytes | byte
Fixed Binary (31 <= p <= 63) | 8 bytes | 8 bytes | byte
Fixed Decimal (p,q) | [(p+2)/2] bytes | byte | byte
Float Binary (p <= 23) | 4 bytes | 4 bytes | byte
Float Binary (p > 23) | 8 bytes | 4 bytes (Intel 32-bit), 8 bytes ( Intel 64-bit, Sparc, RS/6000) | byte
Float Decimal (p) | 12 bytes | 4 bytes | byte
Character (n) | n bytes | byte | byte
Character (n) Varying | n+2 bytes | 2 bytes | byte
Graphic(n) | n*2 bytes | byte | byte
Graphic(n) Varying | n*2+2 bytes | 2 bytes | byte
Widechar (n) | n*2 bytes | byte | byte
Widechar (n) Varying | n*2+2 bytes | Half-word | byte
Bit (n) | n bits | bit | bit
Bit (n) Aligned | [(n+7)/8] bytes | byte | –
Pointer (32-bit) | 4 bytes | 4 bytes | byte
Pointer (64-bit) | 8 bytes | 8 bytes | byte
Picture | n bytes | byte | byte
Label | 8 bytes | 4 bytes | byte
Entry Variable | 8 bytes | 4 bytes | byte
File Variable | 4 bytes | 4 bytes | byte
Structure2 | sum of members + gaps for alignment | max of members | byte
Area (n) | (((n+7)/8)*8)+8 bytes | 8 bytes | –
Offset | 4 bytes | 4 bytes | byte

Subsequent sections provide additional information about the size, alignment, internal representation including byte ordering, and range, where applicable.

The byte ordering on the IBM RS/6000 and Sun SPARC platforms is Big Endian, while the Intel-based platforms have Little Endian byte ordering.

Note:

In the descriptions of data types that follow, the alignment specified is the default, which is ALIGNED for all data types except Bit. For the alignment of each data type with the UNALIGNED attribute, refer to the table above.

  • Fixed Binary (p <= 7)
  • Fixed Binary (8 <= p <= 15)
  • Fixed Binary (16 <= p <= 31)
  • Fixed Binary (31 <= p <= 63)
  • Fixed Decimal (p,q)
  • Float Binary (p <= 23)
  • Float Binary (23 < p <= 52)
  • Float Decimal (p)
  • Character (n)
  • Character (n) Varying
  • Widechar (n)
  • Widechar (n) Varying
  • Bit (n)
  • Bit (n) Aligned
  • Pointer
  • Label
  • Picture
  • Entry
  • File Variable
  • Structure
  • Area (n)
  • Offset
Parent topic: Language Concepts
1

*Fixed Binary (p <= 7 ) is handled as a one-byte signed binary integer by default. To override this default and handle as a two-byte signed binary integer, use the -fb7asfb15 compiler option.

2 See the Structure topic for mapping conventions.


Fixed Binary (p <= 7)

Fixed Binary (p <= 7) is an 8-bit, signed, 2's complement binary integer by default. The low order 7 bits contain the integer, the high order bit contains the sign. The sign bit (S) is 1 if the value is negative, 0 if the value is positive or zero. Use the -fb7asfb15 option to provide compatibility with previous versions of Open PL/I.

Size | Alignment | Range
1 byte | 1 byte | -128 to 127
Parent topic: Data Types


Fixed Binary (8 <= p <= 15)

Fixed Binary (8 <= p <= 15) is a 16-bit, signed, 2's complement binary integer. The low order 15 bits contain the integer, the high order bit contains the sign. The sign bit (S) is 1 if the value is negative, 0 if the value is positive or zero.

Size | Alignment | Range
2 bytes | 2 bytes | -32768 to 32767
Parent topic: Data Types


Fixed Binary (16 <= p <= 31)

Fixed Binary (16 <= p <= 31) is a 32-bit, signed, 2's complement binary integer. The low order 31 bits contain the integer, the high order bit contains the sign. The sign bit (S) is 1 if the value represented is negative.

Size | Alignment | Range
4 bytes | 4 bytes | -2,147,483,648 to 2,147,483,647
Parent topic: Data Types


Fixed Binary (31 <= p <= 63)

Fixed Binary (31 <= p <= 63) is a 64-bit, signed, 2's complement binary integer. The low order 63 bits contain the integer, the high order bit contains the sign. The sign bit (S) is 1 if the value represented is negative.

Size | Alignment | Range
8 bytes | 8 bytes | -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807
Parent topic: Data Types


Fixed Decimal (p,q)

Fixed Decimal (p,q) is a fixed-point number that contains p digits, where q of those digits are fraction digits. Fixed decimal values are typically used only when fraction digits are required. Fixed-point decimal values are always stored as an accurate representation of decimal fractions. The most significant digits are stored at the lowest memory address, and the byte containing the least significant digit and the sign (hexadecimal C for positive or D for negative) is stored at the highest memory address.

Size | Alignment | Range
[(p+2)/2] bytes | byte | -(10p-q - 10-q) to +(10p-q -10-q
Parent topic: Data Types


Float Binary (p <= 23)

Float Binary (p <= 23) is a single-precision, basic format, binary floating-point number (ASCII/IEEE 754-1985 compliant). It contains a 1-bit sign, 8-bit biased exponent (bias = 127), and 23+(1)-bit binary fraction (hidden bit).

An exponent of 255 represents +/- infinity or not-a-number. +/- infinity is represented by an exponent of 255 and zero as the fraction part; the sign bit denotes the + or - infinity. Not-a-number is represented by an exponent of 255 and any non-zero value in the fraction part; the sign bit of not-a-number is not significant. An exponent of 0 denotes a denormalized small value of reduced precision. Both +0 and -0 are possible. Note that the range is approximate and indicates representable values, which include zero and both negative and positive numbers.

Size | Alignment | Approximate Absolute Value of Range
4 bytes | 4 bytes | 1.40E-45 to 3.40E+38
Parent topic: Data Types


Float Binary (23 < p <= 52)

Float Binary (23 < p <= 52) is a double-precision, basic format, binary floating-point number (ANSI/IEEE 754-1985 compliant). It consists of a 1-bit sign, 11-bit biased exponent (bias = 1023), and 52+(1)-bit binary fraction (hidden bit).

An exponent of 2047 represents +/- infinity or not-a-number. +/- infinity is represented by an exponent of 2047 and zero as the fraction part; the sign bit (S) denotes the + or - infinity. Not-a-number is represented by an exponent of 2047 and any non-zero value in the fraction part; the sign bit of not-a-number is not significant. An exponent of 0 denotes a denormalized value of reduced precision. Both +0 and -0 are possible. Note that the range is approximate and indicates representable values, which include zero and both negative and positive numbers.

Size | Alignment | Approximate Absolute Value of Range
Size | Alignment | Approximate Absolute Value of Range
Size | Alignment | Approximate Absolute Value of Range
8 bytes | 4 bytes (Little Endian) 8 bytes (Big Endian) | 4.9E-324 to 1.8E+308
8 bytes | 4 bytes (Little Endian) 8 bytes (Big Endian) | 4.9E-324 to 1.8E+308
8 bytes | 4 bytes (Little Endian) 8 bytes (Big Endian) | 4.9E-324 to 1.8E+308
Parent topic: Data Types


Float Decimal (p)

For compatibility with IBM PL/I, data declared as float decimal is stored and processed by default as 4-byte or 8-byte float binary. (If the specified precision is ? 6, 4-byte float binary is used.)

Alternatively, float decimal data can be stored and processed as 12-byte Binary Coded Decimal BCD float decimal data by using the -nofdasfb ("no float dec as float bin") compiler option. In this case, Float Decimal (p) is a decimal floating-point number, stored in packed decimal format. It consists of a sign, an exponent sign, two bits used for infinity, not-a-number (usually 0), a 3-digit (base 10) exponent and a 17-digit (base 10) fraction. Both the exponent and fraction have a separate sign bit. All digits are packed Binary Coded Decimal (BCD), such that the entire string fits in 96 bits (12 bytes). The fraction contains at least p decimal digits.

Size | Alignment | Approximate Absolute Value of Range
12 bytes | 4 bytes | 9.9999999999999999x10 -999 to 9.9999999999999999x10 999
Parent topic: Data Types


Character (n)

Character (n) is a character-string variable where n is an integer that specifies the length of the string value held by the variable. Character (n) is a sequence of 8-bit ASCll characters stored as 1 character per byte. In Open PL/I, the maximum length of a string variable is 32767 characters.

Size | Alignment
n bytes | byte
Parent topic: Data Types


Character (n) Varying

Character (n) Varying is a character-string variable. The VARYING attribute causes the string variable to hold values of varying length. The representation of a varying string variable in storage is such that any string up to n characters may be held by the variable, and the length of the current string is retained as part of the value. Character (n) Varying is stored as follows: the first two bytes contain the length of the string (represented by a Fixed Binary (15) number) followed by a sequence of 8-bit ASCII characters stored as 1 character per byte. In Open PL/I, the maximum length of a string value is 32767 characters.

Note that the character string is not terminated with a null (ASCII 0) character.

Size | Alignment
n+2 bytes | 2 bytes
Parent topic: Data Types


Widechar (n)

Widechar (n) is a character-string variable where n is an integer that specifies the length of the string value held by the variable. Widechar (n) is a sequence of "byte-pairs" stored as 1 wide character in adjacent bytes (Big Endian order). In Open PL/I, the maximum length of a wide string variable is 16383 wide characters.

Widechar byte table

Size | Alignment
n*2 bytes | byte
Parent topic: Data Types


Widechar (n) Varying

Widechar (n) Varying is a wide character-string variable. The VARYING attribute causes the string variable to hold values of varying length. The representation of a varying string variable in storage is such that any string up to n wide characters may be held by the variable, and the length of the current string is retained as part of the value. Widechar (n) Varying is stored as follows: the first two bytes contain the length of the string (represented by a Fixed Binary (15) number stored in machine native format) followed by a sequence of wide characters stored as 1 wide character (or "byte-pair") in adjacent bytes (Big Endian order). In Open PL/I, the maximum length of a wide string value is 16383 characters.

Widechar (n) Varying byte table

Size | Alignment
n*2+2 bytes | Half-word
Parent topic: Data Types


Bit (n)

Bit (n) is a bit-string variable where n is an integer valued expression that specifies the length of the string value held by the variable. Bit (n) is a sequence of binary digits (bits) that always occupies exactly n bits of storage.

For Intel platforms, using the -bitsltr compiler option stores bit strings as Big-Endian. See -bitsltr in the Compiler Options help topic for more information.

Big-endian platforms:

If the high-order bit of the bit-string does not occur on a byte boundary, the remaining bits in the last byte might be part of another bit-string variable. Within each byte, the bits of the string are stored from the low-order to the high-order bit position. Note the bit positions are zero-relative similar to the hardware bit-numbering. For example, Bit (23) would be stored as follows (assuming an unaligned starting bit offset of 5):

Little-endian platforms:

If the low-order bit of the bit-string does not occur on a byte boundary, the remaining bits in the last byte might be part of another bit-string variable. Within each byte, the bits of the string are stored from the low-order to the high-order bit position (on Intel platforms). Note the bit positions are zero-relative similar to the hardware bit-numbering. For example, Bit (23) would be stored as follows (assuming an unaligned starting bit offset of 5):

On little-endian platforms, bit-strings are essentially stored "right-to-left" according the Intel hardware bit-ordering, but all bit operations are performed according to PL/I language semantics.

Note: Overlaying fixed bin and bit items is non-portable between big-endian and little-endian architectures.
Size | Alignment
n bits | bit (none)
Parent topic: Data Types
Related information
Compiler Options


Bit (n) Aligned

Bit (n) Aligned is a bit-string variable. The ALIGNED attribute causes the bit-string variable for which it is declared to be byte-aligned, resulting in more efficient access. This attribute may also cause the variable to occupy more than n bits, but it does not increase the length of the value that can be stored in the variable. The ALIGNED attribute has no effect on operations performed on the variable, but is considered part of the data type for purposes of argument/parameter matching and storage sharing.

For Intel platforms, using the -bitsltr compiler option stores bit strings as Big-Endian. See -bitsltr in the Compiler Options help topic for more information.

Bit (n) Aligned size is in bytes. If the length, n, is not a multiple of eight (for example, Bit (27) Aligned) then the remaining bits in the last byte are unused. Within each byte, the bits of the string are stored from the high-order to the low-order position. For example, Bit (27) Aligned would be stored as follows:

Size | Alignment
[(n+7)/8] bytes | byte

On Little Endian platforms, bits are reversed on each byte.

Parent topic: Data Types
Related information
Compiler Options


Pointer

Pointer is a 4-byte, 32-bit word variable capable of holding the address of any variable except unaligned bit variables. Pointers are normally used to locate the storage of dynamically allocated BASED variables rather than as a mechanism for accessing another variable's storage. A pointer is used with a template to access the storage to which it points. A pointer value cannot be represented by a constant. Pointer values can be assigned, compared for equality or inequality, passed as arguments, and returned from functions. No calculations or conversions can be performed on them, and they cannot be transmitted in stream I/O.

Size | Alignment
4 bytes | 4 bytes
Parent topic: Data Types


Label

Label is an 8-byte, 32-bit word pair variable consisting of a 4-byte text address and a 4-byte frame pointer value. The text address identifies the first instruction of a labeled statement in the containing procedure. The frame pointer value identifies the address of the stack frame of the block containing the statement. Label values can be assigned, compared for equality or inequality, passed as arguments, and returned from functions. No calculations or conversions can be performed on them, and they cannot be transmitted in stream I/O.

Size | Alignment
8 bytes | 4 bytes
Parent topic: Data Types


Picture

Picture is a fixed-point decimal value stored internally as a character string. The string contains the characters that represent the numeric value, and may be formatted with special embedded symbols such as a period (.) or a comma (,). Picture data is best used to manipulate a quantity arithmetically and then print or display its value.

Size | Alignment
n bytes | byte
Parent topic: Data Types


Entry

Entry is an 8-byte, 32-bit word pair variable consisting of a 4-byte descriptor pointer and a 4-byte frame pointer value. The descriptor pointer points to a data area that specifies the text address of the procedure entry and the table of contents pointer for the procedure. The frame pointer (relevant only with internal procedures) designates the stack frame of the containing procedure, if any. For external procedures, the frame pointer value is zero (0).

Size | Alignment
8 bytes | 4 bytes
Parent topic: Data Types


File Variable

File Variable is represented internally as a 4-byte, 32-bit word containing the address of a file control block. When evaluated, the value of the file variable is the address of the file control block for the file with which the variable is associated. A file variable can be assigned any file value; it is declared using both the FILE and VARIABLE attributes.

Size | Alignment
4 bytes | 4 bytes
Parent topic: Data Types


Structure

Structure is a hierarchically ordered set of values that may be of different data types. The immediate components of a structure are called "members" of the structure. An entire structure can be transmitted in stream or record I/O, passed as an argument, or assigned to another structure of identical size and shape and having members of corresponding identical data types. No conversions or calculations can be performed on entire structures.

Size | Alignment
Sum of members + gaps for alignment | Most stringent of members' alignment requirements

In Open-PL/I, structure mapping is as follows:

  • Each member is aligned to its natural boundary (offset from the start of the structure) as determined by the native machine architecture. Each member offset is effectively "pushed ahead" to map to its natural boundary, and where necessary, pad bytes may be introduced.
  • The alignment of the top-level structure (and substructures) will inherit the most stringent alignment requirement of its members.
Parent topic: Data Types


Area (n)

Area (n) is a variable describing a region of storage whose size in bytes is defined by the integer n. An area variable is a region of storage in which based variables can be allocated and freed. An area can be passed as an argument or it can be assigned to another area. It can also be transmitted in its entirety in a record I/O operation. No other operations, calculations, or conversions can be performed on area variables.

Size | Alignment
n bytes rounded to 8 byte boundary, plus 8 byte header [ (((n+7)/8)*8)+8] bytes | 8 bytes

Related Topics

Offset

Parent topic: Data Types
Related information
Offset


Offset

An offset variable is a locator used only in conjunction with an area variable. The value of an offset variable specifies the location of a based variable within an area, relative to the beginning of the area.

Offset variables can be assigned, compared for equality and inequality, passed as arguments, and returned as function results. No calculations or conversions can be performed on them, except in the context of explicit conversion to a Pointer, using Open PL/I's POINTER built-in function.

Size | Alignment
4 bytes | 4 bytes
Parent topic: Data Types
Related information
Area n


Arithmetic Precision

Each arithmetic data type has a default precision and a maximum precision as specified in Table 2-2. The range of the scale factor of fixed-point decimal data is 0 through 31 (0 ? q ? 31).

Data Type | Maximum Precision | Default Precision
Fixed Binary | 31 | 15*
Fixed Decimal | 31 | 5
Float Binary | 52 | 23
Float Decimal | 16 | 6

* The -longint option changes the default precision of fixed binary from 15 to 31.

Parent topic: Language Concepts


External Procedures

Open PL/I adheres to the calling conventions of the native architecture. Programs compiled by Open PL/I can be linked with object modules produced by other language products, and the resulting object program will run if the following conditions are met:

  • The calling conventions used by other language product(s) also adhere to the calling conventions of the native architecture. Note that the system C compiler on UNIX and the Windows Visual C/C++ compiler meet this requirement.
  • Declarations for formal and actual parameters in the calling and called programs must be written in their respective languages, so that the data representations assumed in the declarations agree with each other.
  • External Names
Parent topic: Language Concepts


External Names

Certain rules apply with regard to name length and the use of lowercase letters when specifying an identifier name:

  1. Name length: Open PL/I allows names up to 256 characters long.
  2. Lowercase names: By default, Open PL/I treats all names, including external names, as if all lowercase letters were upper case. When interfacing with non-PL/I external procedures, it may be necessary to work around this. For example, the C language preserves the case of all external names.

    If Open PL/I is calling a C function or vice-versa, one of the following options is available.

    • Spell with uppercase letters the external names in the C function where needed.
    • Use the EXTERNAL('name') option on the PLI ENTRY declaration to specify the exact name of the external C entry point.
    • Use the Open PL/I -lowercase Compiler option, which maps all external names to lower case instead of upper case. Note that all external names produced are lower case, not just the entry point to a procedure.
Parent topic: External Procedures


Maximum Number of Arguments for a Function or Subroutine Call

The maximum number of arguments that may be passed in an Open PL/I program is given by the following formula, which holds generally for any function or subroutine call argument list:

N + M= 241

where:

N | Is the actual number of arguments specified.
M | Is the position of the last *-extent argument, or zero if none exists.

Example:

DECLARE (S, T, U, V) CHAR (32),
   (I, J, K, L) BINARY (15),
   MYSUB ENTRY (BINARY(15), BINARY (15), CHAR(*),
         CHAR(*), BINARY(15), BINARY(15));
.
.
.
   CALL MYSUB(I,J,K,S,T,L);

where:

N | = 6 (the number or arguments specified)
M | = 5 (the position of "T" in the argument list)

which gives:

N+ M = 11 (6 actual arguments; 3 dummy descriptors for I, J, and K; and 2 actual descriptors for S and T).
Parent topic: Language Concepts


Open PL/I Calling Conventions

The following sections describe the calling conventions for HP, Intel, RS/6000, and Sun Sparc systems. All LPI-series languages compilers use the following calling conventions and are compatible with Open PL/I.

  • Calling Other Languages
  • Argument Passing Conventions
  • Register Save Conventions
  • Function Result Conventions
  • Open PL/I Equivalent Data Types
Parent topic: Language Concepts


Calling Other Languages

If you are calling a function written in another language, the result type must be able to be mapped to a PL/I data type.

C often expects character strings to be null terminated, that is, the string is delimited by an '\0' byte immediately following the last character of interest. When constructing a character value in PL/I that is passed to a C function expecting a null terminator, the PL/I procedure must supply an explicit null character in the appropriate position. The BYTE built-in function can be used for this purpose, as shown in the following example.

call CFUNC('abcde' || BYTE(0))

or without the BYTE built-in using z-character constants,

call CFUNC('abcde'Z)
  • C Calling Conventions
Parent topic: Open PL/I Calling Conventions


C Calling Conventions

The following program illustrates how to declare and call two standard C library functions, "atoi" and "strtol":

int atoi(const char *str)

long strtol(const char *str, char **endptr, int base)

Please note the following points:

  1. Since C is case-sensitive and PL/I is not, use EXTERNAL('name') to map the PL/I name to the function's real name.
  2. Since C arguments are passed by immediate value, specify the BYVALUE attribute for FIXED BINARY parameters.
  3. Because PL/I arguments are normally passed by reference, the BYVALUE attribute is not necessary for char * arguments declared CHARACTER(n). However, when a char * argument is declared POINTER, as in the ATOI_2 declaration, the BYVALUE attribute is required.
  4. By convention, C strings are terminated with a NULL byte.
  5. In this example, although char * is declared CHARACTER(80), any length long enough to hold the string and a terminating null byte would be all right. Of course, if the C function expected a pointer to a character string of a certain length, the PL/I and C declarations should agree.
  6. Note the use of the z-character constants for compatibility with C-style null-terminated strings, and the use of the SYSNULL() built-in, which returns 0, as opposed to the NULL() built-in, which returns -1 by default.
    CALLC: PROCEDURE OPTIONS(MAIN);

DECLARE

ATOI   ENTRY(CHARACTER(80))
       RETURNS(FIXED BINARY(31))
       EXTERNAL('atoi'),

ATOI_2 ENTRY(POINTER BYVALUE)
       RETURNS(FIXED BINARY(31))
       EXTERNAL('atoi'),

STRTOL ENTRY(CHARACTER(80),
             POINTER BYVALUE,
             FIXED BINARY(31) BYVALUE)
       RETURNS(FIXED BINARY(31))
       EXTERNAL('strtol'),

BASE   FIXED BINARY(31),
ENDPTR POINTER,
INT    FIXED BINARY(31),
LONG   FIXED BINARY(31),
STR    CHARACTER(80),
STRPTR POINTER;

STR    = '2147483647'z;
INT    = ATOI(STR);

PUT SKIP LIST(INT);

STRPTR = ADDR(STR);
INT    = ATOI_2(STRPTR);

PUT SKIP LIST(INT);

STR    = '0x7fffffff'z;
ENDPTR = SYSNULL();
BASE   = 16;
LONG   = STRTOL(STR, ENDPTR, BASE);

PUT SKIP LIST(LONG);

PUT SKIP LIST(STRTOL('0x7fffffff'z, SYSNULL(), 16));

END CALLC;
Parent topic: Calling Other Languages


Argument Passing Conventions

The following sections detail the argument passing conventions for HP, Intel, RS/6000, and Sun Sparc platforms.

  • HP Argument Passing Conventions (32-bit)
  • Intel Argument Passing Conventions (32-bit)
  • RS/6000 Argument Passing Conventions (32-bit)
  • Sun Sparc Argument Passing Conventions (32-bit)
Parent topic: Open PL/I Calling Conventions


HP Argument Passing Conventions (32-bit)

Arguments are passed in General Purpose Registers (GR) 26–23, Single-Precision Floating-Point Registers (FR) 4–7, Double-Precision Floating-Point Registers (FR) 5 and 7, and in the parameter area of the stack, according to the Open PL/I standard calling conventions.

  • If the function returns a value in a temporary storage area, a pointer to that area is passed in GR28.
  • The argument list contains addresses of the actual arguments in order or their appearance. If any arguments have the BYVALUE attribute, the actual argument is passed.
  • If OPTIONS(VARIABLE) is used, any missing arguments are replaced by null pointers.
  • If any of the function's parameters have variable extents, for example, asterisks(*), the addresses of dope vectors describing the arguments are appended to the explicit argument list.
Parent topic: Argument Passing Conventions


Intel Argument Passing Conventions (32-bit)

  • The calling procedure pushes the addresses of the actual arguments (pointers) onto the stack in the reverse order of their appearance in an argument list. In other words, the address of the last argument is pushed first and the address of the first argument is pushed last.
  • A call to a function returning one of the data types that requires a return temporary must push a pointer to the area for the result value onto the stack.

The external procedure is called by executing a CALL instruction.

Parent topic: Argument Passing Conventions


RS/6000 Argument Passing Conventions (32-bit)

Arguments are passed in General Purpose Registers (GPR) 3–10, Floating-point Registers (FPR) 1–13, and in the parameter area of the stack according to the Open PL/I standard calling conventions.

  • If the function returns a value in a temporary storage area, a pointer to that area is passed in GPR3 and all other arguments are displaced by one.
  • The argument list contains addresses of the actual arguments in order of their appearance. If any arguments have the BYVALUE attribute, the actual argument is passed.
  • If OPTIONS(VARIABLE) is used, any missing arguments are replaced by null pointers.
  • If any of the function's parameters have variable extents, for example asterisks (*), the addresses of dope vectors describing the arguments are appended to the explicit argument list.
Parent topic: Argument Passing Conventions


Sun Sparc Argument Passing Conventions (32-bit)

External procedures are called using the CALL instruction and are returned using the RET and RESTORE sequence.

  • The first six parameters are passed in the output registers; that is, the first parameter is passed in register o0, the second in register o1 and the sixth one in register o5. Parameters beyond the sixth are passed on the stack.
  • If OPTIONS(VARIABLE) is used, any missing arguments in the call to the procedure are replaced by null pointers.
  • The external procedure is called by executing a CALL instruction.
Parent topic: Argument Passing Conventions


Register Save Conventions

The following sections detail the register save conventions for HP, Intel, and Sun Sparc systems.

  • HP Register Save Conventions (32-bit)
  • Intel Register Save Conventions (32-bit)
  • RS/6000 Register Save Conventions (32-bit)
  • Sun Sparc Register Save Conventions (32-bit)
Parent topic: Open PL/I Calling Conventions


HP Register Save Conventions (32-bit)

The called procedure is expected to save and restore values in registers GR3–GR18 and FR12–FR21. The calling procedure can assume that those registers are preserved across the call. The function result is in GR28, FR4, or the result temporary provided by the caller, depending on the result data type. For more information, see the section HP Function Result Conventions.

Parent topic: Register Save Conventions
Related information
HP Function Result Conventions


Intel Register Save Conventions (32-bit)

The contents of ebx, esi, and edi must be preserved across a subroutine call. If a subroutine uses one of these registers, it must save the original value and restore it before returning to the caller.

Registers eax, ecx, and edx are scratch registers. A subroutine can change the value in a scratch register without saving its previous value.

When the Intel floating-point coprocessor is used, the floating-point stack registers must be empty before entry and upon exit from a subroutine. However, if the subroutine returns a floating-point value, the value is returned on top of the stack in register fp0 and the remainder of the stack is empty.

A called procedure is responsible for establishing a new stack frame for itself and saving and restoring all preserved registers. The procedure establishes the stack frame with the following sequence:

pushl ebp
movl esp, ebp
subl #framesize, esp
pushl ebx         //only if used within function
pushl esi         //only if used within function
pushl edi         //only if used within function

Note that the code sequence may be abbreviated if -opt is specified.

A return must store any function result value, restore any preserved registers it used, pop its stack frame, and return to the caller.

A procedure that returns one of the data types that requires a return temporary must remove the extra pointer(s) from the stack entry; callers to such routines push these hidden arguments. The called routine must load register eax with the pointer to the return area that its caller passed before returning. Such a routine will start with the following code before establishing a frame:

popl edx
xchgl edx, 0 (esp)

Then it saves the return pointer in a local variable in its stack frame.

Parent topic: Register Save Conventions


RS/6000 Register Save Conventions (32-bit)

The called procedure is expected to save and restore values in registers GPR13 through GPR31 and FPR14 through FPR31. The calling procedure can assume that those registers are preserved across the call. The function result is in GPR3, FPR1, or the result temporary provided by the caller, depending on the result data type.

Parent topic: Register Save Conventions


Sun Sparc Register Save Conventions (32-bit)

The called procedure is expected to save and restore all local and input registers (10 through 17 and i0 through i7). The calling procedure can assume that only these registers are preserved across the call. The function result is general ally in o0, f0, or both f0 and f1, or the result temporary provided by the caller, depending on the result data type. For more information, see the section Sun Sparc Function Result Conventions.

A called procedure is responsible for establishing a new stack frame for itself and saving and restoring all local and input registers. This is accomplished by a SAVE instruction. Before returning, the called procedure must store any function result value, restore all local and input registers, and adjust the stack frame. This is accomplished by a load of i0, f0, or both f0 and f1, or a store to a result temporary and a RESTORE instruction.

Parent topic: Register Save Conventions
Related information
Sun Sparc Function Result Conventions


Function Result Conventions

A function returns its result to the caller in one of four ways. The following sections detail the function result conventions on HP, Intel, RS/6000, and Sun Sparc systems.

  • HP Function Result Conventions (32-bit)
  • Intel Function Result Conventions (32-bit)
  • RS/6000 Function Result Conventions (32-bit)
  • Sun Sparc Function Result Conventions (32-bit)
  • Return of Data Types
Parent topic: Open PL/I Calling Conventions


HP Function Result Conventions (32-bit)

A function procedure returns its result value to the calling procedure in one of three ways, depending upon the data type: in register GR28, in register FR4, or in a temporary storage area provided by the caller.

If the result is returned in a temporary storage area, the calling procedure provides the temporary area and passes its address in GR28.

Parent topic: Function Result Conventions


Intel Function Result Conventions (32-bit)

On Intel x86 systems, the result of a function is returned in one of the following three ways, depending upon the result's data type and if the floating-point coprocessor is used:

  • In register eax
  • In a temporary storage area provided by the caller
  • On top of the Intel floating-point coprocessor's stack in register fp0
Parent topic: Function Result Conventions


RS/6000 Function Result Conventions (32-bit)

A function procedure returns its result value to the calling procedure in one of three ways, depending upon the data type:

  1. In register GPR3
  2. In register FPR1
  3. In a temporary storage area provided by the caller

If the result is returned in a temporary storage area, the calling procedure provides the temporary area and passes its address as the first (hidden) parameter in the call.

Parent topic: Function Result Conventions


Sun Sparc Function Result Conventions (32-bit)

On the Sun Sparc, the result of a function is returned in one of the following four ways, depending upon the result's data type:

  1. In register o0
  2. In a temporary storage area
  3. In register f0
  4. In registers f0 and f1

On Sun Sparc systems, the calling procedure provides the temporary area and stores the address to the temporary area in the one-word hidden parameter of the user frame at %sp+0x40 prior to the call.

Parent topic: Function Result Conventions


Return of Data Types

The table below lists the Open PL/I data types and the registers to which they are returned on each platform.

Open PL/I Data Type | Register Returned in
 | HP | Intel | RS/6000 | Sun Sparc
Fixed Binary Character(1), not * or Varying Bit(1), not * Pointer Offset File | GR28 | eax | GPR3 | o0
Float Binary | FR4 | on top of the floating-point coprocessor stack | FPR1 | f0/f1
Fixed Decimal Float Decimal Character( n), n > 1 or n = * Character( n) Varying Bit( n), n > 1 or n = * Picture Label Entry | Returned in Temporary Storage Area
Parent topic: Function Result Conventions


Open PL/I Equivalent Data Types

This table lists compatible data types for determining equivalent argument type correspondence. Some data types (for example, char in C) are used more than once in the table to show the correspondence of equivalent types in more than two languages. The subscripts used in the table have the following meanings:

PL/I | COBOL | C | C++ | FORTRAN | BASIC | PASCAL
Fixed Bin, P <= 7 | COMP PIC S9 (1) – S9 (2) | char | char | INTEGER*1 | – | –
Fixed Bin, 8 <= P <= 15 | COMP PIC S 9 (3) – S 9 (4) | short | short | INTEGER*2 | INTEGER (%) | Integer
Fixed Bin, P >15 | COMP PIC S 9 (5) – S 9 (9) | int or long | int or long | INTEGER*4 | – | Integer
– | – | char | char | INTEGER*1 | – | Packed Array[1...5]
Character (n) | DISPLAY A(n) or PIC X(n) | char [n] | char[n] | CHARACTER*n | – | –
Character (N) Varying | DISPLAY PIC X OCCURS num1 to num2 DEPENDING on N | struct {short s; char c[n];} | struct {short s; char c[n];} | – | – | Char
Character (1) | DISPLAY PIC X | char | char | CHARACTER*1 | – | –
Character (*) | – | char[ ] | char[ ] | – | – | –
Fixed Decimal | COMP–3 PIC S9 (n) | – | – | – | – | –
 | DISPLAY PIC S9(n) SIGN TRAILING | – | – | – | – | –
– | DISPLAY PIC S9(n) SIGN LEADING SEPARATE | – | – | – | – | –
– | DISPLAY PIC S9(n) SIGN TRAILING SEPARATE | – | – | – | – | –
Bit(1) | – | – | – | – | – | –
Bit(1) Aligned | – | char | char | – | – | Boolean
Bit(N) Aligned | COMP–5 PIC [S] 9 (n), n<5 | – | – | – | – | Set
– | – | int or long | int or long | LOGICAL*4 | – | –
– | – | short | short | LOGICAL*2 | – | –
– | – | char | char | LOGICAL*1 /BYTE | – | –
Float Bin, p > 23 | COMP–2 | double | double | REAL*8 | REAL (#) (MBASIC) | –
Float Bin, p <= 22 | COMP–1 | float | float | REAL*4 | REAL (1) (MBASIC) | Real
– | – | struct {float real, imaginary;} | struct {float real, imaginary;} | COMPLEX*8 | – | –
– | – | struct {double real; double imaginary} | #include <complex.h> class complex | COMPLEX*16 | – | –
Pointer | – | Pointer | Pointer | – | – | Pointer
Label | – | – | – | alternate return | – | –
Entry | DISPLAY PIC X(32) | – | – | Dummy procedure | – | –
Float Decimal | – | – | – | – | REAL (CBASIC) | –
– | – | – | – | – | STRING ($) | –
Area | – | – | – | – | – | –
Offset | COMP PIC S 9 (5) – S 9 (9) | int or long | int or long | INTEGER*4 | – | integer
Parent topic: Open PL/I Calling Conventions


Special Programming Tasks

  • XML Parser Support in PL/I
    Brief description of concept. Should be written as a fragment. Contains no more than two sentences.
Parent topic: Language Concepts


XML Parser Support in PL/I

PL/I provides a SAX-like event-based interface for parsing XML documents. The parser invokes an application-supplied handler for parser events, passing references to the corresponding document fragments.

For an event-based API, the parser reports events to the application through call backs. Events include the start of the document, the beginning of an element, the end of the document and other document-related activities. The application must provide a handler to deal with each of the events reported by the parser. The simple SAX API follows SAX interfaces provided for other languages such as C, for which there is no standard.

The PL/I SAX parsers include the PLISAXA, PLISAXB, and PLISAXC built-in subroutines. THE PLISAXD built-in subroutine is not yet supported.

The parser can:

  • Provide high-performance, but non-standard interfaces.
  • Support XML files encoded in either Unicode UTF-16 or any of several single-byte code pages.
  • Check XML well-formedness and generate exception events.

XML documents have two levels of conformance: well-formedness and validity, both of which are defined in the XML standard. Basically, an XML document is well-formed when it complies with the basic XML grammar, and with a few specific rules, such as the requirement for matching start and end element tags names. A well-formed XML document also includes an associated document type declaration (DTD) that complies with the constraints expressed in the DTD.

A PL/I function must accept the appropriate parameters and return the appropriate return value for each parser event. Also, the return value must be returned as a BYVALUE.

XML Parser Support Restrictions

If using the -ebcdic option to compile your program, the callback event logic should account for the fact that the data passed back to the call backs is in ASCII, even if the input format was in EBCDIC. Because of this, the data must be translated prior to use within the callbacks. In addition, all reference values passed as a FIXED BIN(31) are for ASCII character encoding.

It is assumed that your program is built using the -bigendian compiler option if operating on an Intel Chip. If compiling your program without using the -bigendian compiler option, then you must convert the parameter types from big-endian to little-endian prior to use.

  • Using the PLISAXA and PLISAXB XML parsers
    Explains the use of the PLISAXA and PLISAXB built-ins for XML parsing.
  • Notes on PLISAXA and PLISAXB XML parsing support and differences with IBM's implementation
  • Using the PLISAXC XML parser
  • Notes on PLISAXC XML parsing support and differences with IBM's implementation
    Describes restrictions to PLISAXC XML parsing support on Open PL/I.
  • SAX event structures
  • XML document coded character sets
  • Exceptions
Parent topic: Special Programming Tasks


Using the PLISAXA and PLISAXB XML parsers

The PLISAXA and PLISAXB built-in subroutines provide basic XML parsing capability. XML parsing lets PL/I programs consume and use inbound XML documents, check the well-formedness of the documents, and react to their contents. SAX parsing is based on the libxml2 XML parser.

These subroutines do not provide XML generation, which must instead be accomplished by PL/I program logic or by using the XMLCHAR built-in function.

PLISAXA and PLISAXB have no special environmental requirements. They execute in all the principal run-time environments, including CICS, IMS, WebSphere MQ, and TSO.

The PLISAXA and PLISAXB built-ins do not support XML name spaces or Unicode UTF-8 documents. They require that the entire XML document be passed in a buffer or a file before any parsing is performed. However, the PLISAXC built-in does not have these limits.

Parent topic: XML Parser Support in PL/I
Related reference
PLISAXA Subroutine
PLISAXB Subroutine
XMLCHAR Function


Notes on PLISAXA and PLISAXB XML parsing support and differences with IBM's implementation

The Event Handler structure must be AUTOMATIC storage and initialized with the call back values or be assigned prior to invoking PLISAXA or PLISAXB. The Event Handler structure must be populated with an appropriate callback for each element of the structure. If the assignment is done manually using assignment statements, then it can be AUTOMATIC or STATIC.

The following are considerations if migrating an existing z/OS based application:

  • A call back EVENT must be provided for every member of the Event Handler structure. Change ENTRY LIMITED alias definitions for Event Handler Items to ENTRY to prevent the compiler from generating an E Level diagnostic. Also, remove all references to LINKAGE(OPTLINK) from ENTRY and Procedure declarations.
  • The event unknown_attribute_reference (E20), which is part of the PLISAXA and PLISAXB event structure (but not part of PLISAXC) is generated with the same content as IBM's SAX processor but occurs earlier in the parsing.
  • The reference for the event unknown_content_reference (E21) is expanded to be its actual value.
  • The events start_of_prefix_mapping (E22) and end_of_prefix_mapping (E23) are currently not supported to maintain compatibility with applications written using IBM's PLISAXA and PLISAXB functionality.
  • When using the SAX Parser, the exception event (E24) is driven only one time indicating an error, as opposed to having the exception event driven one time per character. See the topic XML Parsing Exception Event error codes for a list of Micro Focus error codes for the exception event (E24).
  • PLISAXB accepts filenames as the third parameter in the form file://dd:ddname under batch, where ddname is the name of the DD statement that specifies the file. The character string specifying the input file should have no leading or trailing blanks. If this is not the format, the parameter value is assumed to be the actual filename. Only files of RECFM=F, FB, FS, FBS and LSEQ are acceptable input.
Parent topic: XML Parser Support in PL/I
Related reference
PLISAXA Subroutine
PLISAXB Subroutine


Using the PLISAXC XML parser

The PLISAXC built-in subroutine provides basic XML parsing capability. XML parsing lets PL/I programs consume and use inbound XML documents, and react to their contents. SAX parsing is based on the libxml2 XML parser.

The XML parser used by PLISAXC is non-validating, but does partially check for well-formedness errors, and generates exception events if it discovers any. It does not provide XML generation, which must instead be accomplished by PL/I program logic or by using the XMLCHAR built-in function.

PLISAXC has no special environmental requirements except that it is not supported in AMODE 24. It executes in all the principal run-time environments, including CICS, IMS, WebSphere MQ, and TSO.

Parent topic: XML Parser Support in PL/I
Related reference
PLISAXC Subroutine


Notes on PLISAXC XML parsing support and differences with IBM's implementation

If using the FLAGS parameter of the content_characters event as a BIT(8) array, you must take into account bit ordering differences on Intel from z/OS. If evaluated as a single byte and not a bit array, then bit ordering matches z/OS bit ordering. See the online help topic Bit (n) for a discussion of bit ordering in a bit array on little endian platforms.

If XML content contains predefined reference characters, separate content_characters events are driven for the characters preceding the predefined reference characters, the reference character, and the characters after the reference characters. For example, the XML snippet <meat>Ham &amp; turkey</meat> generates three content_characters events using PLISAXC; one for Ham, one for &, and one for Turkey.

For the FLAGS parameter of the content_characters event, the flag to indicate the next event contains content_characters ('80'x). This currently only indicates if the next event contains content_characters when the current event contains a character which must be escaped back to XML. Also, the flag to indicate that no characters are escaped back to XML ('40'x) is only set if the character string contains one of the predefined reference characters for PLISAXA.

Parent topic: XML Parser Support in PL/I
Related reference
PLISAXC Subroutine
Related information
Bit (n)


SAX event structures

  • SAX event structure descriptions for PLISAXA and PLISAXB
    Describes the 24 ENTRY variables in the SAX event structure for PLISAXA and PLISAXB.
  • SAX event structure descriptions for PLISAXC
    Describes the 24 ENTRY variables in the SAX event structure for PLISAXA and PLISAXB.
  • PLISAXA and PLISAXB XML Parser event function parameters
  • PLISAXC XML Parser event function parameters
  • XML Parser exception event error codes
    Lists the available exception event error codes for PL/I XML parsing.
  • PLISAXA and PLISAXB event structure example
    Shows an example of a SAX event structure for PLISAXA and PLISAXB.
  • PLISAXC event structure example
    Shows an example of a SAX event structure for PLISAXC.
  • Event differences
    Describes the event structure differences between PLISAXA/PLISAXB and PLISAXC
Parent topic: XML Parser Support in PL/I


SAX event structure descriptions for PLISAXA and PLISAXB

The event structure has 24 ENTRY variables. These variables point to functions invoked by the parser for various events.

Descriptions of each event in this topic refer to this XML document example.
xmlDocument =
   '<?xml version="1.0" standalone="yes"?>'
|| '<!--This document is just an example-->'
|| '<sandwich>'
|| '<bread type="baker&quot;s best"/>'
|| '<?spread please use real mayonnaise ?>'
|| '<meat>Ham &amp; turkey</meat>'
|| '<filling>Cheese, lettuce, tomato, etc.</filling>'
|| '<![CDATA[We should add a <relish> element in future!]]>'
|| '</sandwich>'
|| 'junk';

The term XML text in the descriptions is the string, which is formed based on the pointer and length passed to the event. The parser may recognize these events in their order of appearance in the structure.

start_of_document
Occurs once, at the beginning of parsing the document. The parser passes the address and length of the entire document, including any line-control characters, such as LF (Line Feed) or NL (New Line). For the above example, the document is 305 characters in length.
version_information
Occurs within the optional XML declaration for the version information. The parser passes the address and length of the text containing the version value ("1.0" in the example above).
encoding_declaration
Occurs within the XML declaration for the optional encoding declaration. The parser passes the address and length of the text containing the encoding value.
standalone_declaration
Occurs within the XML declaration for the optional standalone declaration. The parser passes the address and length of the text containing the standalone value ("yes" in the example).
document_type_declaration
Occurs when the parser finds the document type declaration. A document type declaration begins with the character sequence <!DOCTYPE" and ends with a > character. Fairly complicated grammar rules describe the content in between.

The parser passes the address and length of the text containing the entire declaration. This includes the opening and closing character sequences. This is the only event where XML text includes the delimiters. The example above does not have a document type declaration.

end_of_document
Occurs once, when document parsing has completed.
start_of_element
Occurs once for each element start tag or empty element tag. The parser passes the address and length of the text containing the element name. The first start_of_element event during parsing in the example contains the string sandwich.
attribute_name
Occurs for each attribute in an element start tag or empty element tag, after recognizing a valid name. The parser passes the address and length of the text containing the attribute name. The only attribute name in the example is type.
attribute_characters

Occurs for each fragment of an attribute value. The parser passes the address and length of the text containing the fragment. An attribute value normally consists of a single string only, even if it is split across lines:

<element attribute="This attribute value is
split across two lines"/>

The attribute value might consist of multiple pieces, however. For instance, the value of the type attribute in the sandwich example at the beginning of the example has three fragments: the string baker, the single character ' and the string s best. The parser passes these fragments as three separate events. It passes each multiple-character string as attribute_characters events, and the single character as an attribute_predefined_reference event.

attribute_predefined_reference
Occurs in attribute values for the five pre-defined entity references &, ', >, <, and ". The parser passes a CHAR(1) or WIDECHAR(1) value that contains one of &, ', >, <, or " respectively.
attribute_character_reference

Occurs in attribute values for numeric character references of the form

&#dd;

or

&#xhh;

where d and h represent decimal and hexadecimal digits, respectively. The parser passes a FIXED BIN(31) value that contains the corresponding integer value.

end_of_element
Occurs once for each element end tag or empty element tag whenever the parser recognizes a closing angle bracket of the tag. The parser passes the address and length of the text containing the element name.
start_of_CDATA_section
Occurs at the start of a CDATA section. CDATA sections begin with the string <![CDATA[ and end with the string ]], and are used to escape blocks of text containing characters that would otherwise be recognized as XML markup. The parser passes the address and length of the text containing the opening characters <![CDATA[. The parser also passes the content of a CDATA section between these delimiters as a single content-characters event. The content-characters event is passed the text We should add a <relish> element in future!.
end_of_CDATA_section
This event occurs when the parser recognizes the end of a CDATA section. The parser passes the address and length of the text containing the closing character sequence, “]]”.
content_characters

This event represents the main body of an XML document. This is the character data between element start and end tags. The parser passes the address and length of the text containing this data, which usually consists of a single string only, even if it is split across lines:

<element1>This character content is
split across two lines"</element1>

If the content of an element includes any references or other elements, the complete content may comprise several segments.

For example, the content of the meat element in the example includes the string Ham , the character & and the string turkey. There is a trailing space in the first string fragment and a leading space in the second string fragment. The parser passes these content fragments as separate events. It passes the string content fragments, Ham and turkey, as content_characters events, and the single & character as a content_predefined_reference event. The parser also uses the content_characters event to pass the text of CDATA sections to the application.

content_predefined_reference
Occurs in element content for the pre-defined entity references &, ', >, <, and ". The parser passes a CHAR(1) or WIDECHAR(1) value that contains one of &, ', >, <, or ", respectively.
content_character_reference

Occurs in element content for numeric character references of the form:

&#dd;

or

&#xhh;

where d and h represent decimal and hexadecimal digits, respectively. The parser passes a FIXED BIN(31) value that contains the corresponding integer value.

processing_instruction
Processing instructions (PIs) allow XML documents to contain special instructions for applications. This event occurs when the parser recognizes the name following the PI opening character sequence, <?. The event also covers the data following the PI target, up to but not including the PI closing character sequence, ?>. Trailing, but not leading white space characters in the data are included. The parser passes the address and length of the text containing the target, spread in the example, and the address and length of the text containing the data, please use real mayonnaise in the example.
comment
Occurs for any comments in the XML document. The parser passes the address and length of the text between the opening and closing comment delimiters, <!-- and -->, respectively. The only comment text in the example is This document is just an example.
unknown_attribute_reference
Occurs within attribute values for entity references other than the pre-defined entity references, listed for the event attribute_predefined_reference. The parser passes the address and length of the text containing the entity name.
unknown_content_reference
Occurs within element content for entity references other than the pre-defined entity references listed for the content_predefined_reference event. The parser passes the address and length of the text containing the entity name.
start_of_prefix_mapping
This event is currently not generated.
end_of_prefix_mapping
This event is currently not generated.
exception
The parser generates this event when it detects an error processing the XML document.
Parent topic: SAX event structures


SAX event structure descriptions for PLISAXC

The event structure has 19 ENTRY variables. These variables point to functions invoked by the parser for various events.

Descriptions of each event in this topic refer to this XML document example.
xmlDocument =
   '<?xml version="1.0" standalone="yes"?>'
|| '<!--This document is just an example-->'
|| '<sandwich>'
|| '<bread type="baker&quot;s best"/>'
|| '<?spread please use real mayonnaise ?>'
|| '<meat>Ham &amp; turkey</meat>'
|| '<filling>Cheese, lettuce, tomato, etc.</filling>'
|| '<![CDATA[We should add a <relish> element in future!]]>'
|| '</sandwich>'
|| 'junk';

The term XML text in the descriptions is the string, which is formed based on the pointer and length passed to the event. The parser may recognize these events in their order of appearance in the structure.

start_of_document
Occurs once, at the beginning of parsing the document. The parser passes no parameters to this event (except the user token).
version_information
Occurs within the optional XML declaration for the version information. The parser passes the address and length of the text containing the version value ("1.0" in the example above).
encoding_declaration
Occurs within the XML declaration for the optional encoding declaration. The parser passes the address and length of the text containing the encoding value.
standalone_declaration
Occurs within the XML declaration for the optional standalone declaration. The parser passes the address and length of the text containing the standalone value ("yes" in the example).
document_type_declaration
Occurs when the parser finds the document type declaration. A document type declaration begins with the character sequence <!DOCTYPE" and ends with a > character. Fairly complicated grammar rules describe the content in between.

The parser passes the address and length of the text containing the entire declaration. This includes the opening and closing character sequences. This is the only event where XML text includes the delimiters. The example above does not have a document type declaration.

end_of_document
Occurs once, when document parsing has completed. The parser passes no parameters to this event (except the user token).
start_of_element
Occurs once for each element start tag or empty element tag. The parser passes the address and length of the text containing the element name as well as any applicable namespace information. The first start_of_element event during parsing in the example contains the string sandwich.
attribute_name
Occurs for each attribute in an element start tag or empty element tag, after recognizing a valid name. The parser passes the address and length of the text containing the attribute name as well as any applicable namespace information. The only attribute name in the example is type.
attribute_characters

Occurs for each fragment of an attribute value. The parser passes the address and length of the text containing the fragment. An attribute value normally consists of a single string only, even if it is split across lines:

<element attribute="This attribute value is
split across two lines"/>
end_of_element
Occurs once for each element end tag or empty element tag whenever the parser recognizes a closing angle bracket of the tag. The parser passes the address and length of the text containing the element name as well as any applicable namespace information.
start_of_CDATA_section
Occurs at the start of a CDATA section. CDATA sections begin with the string <![CDATA[ and end with the string ]]. They are are used to escape blocks of text containing characters that would otherwise be recognized as XML markup. The parser passes no parameters to this event (except the user token).

After this event, the parser passes the content of a CDATA section between these delimiters as as one or more content-characters events. In the preceding example, the content-characters event is passed the text We should add a <relish> element in future!

end_of_CDATA_section
This event occurs when the parser recognizes the end of a CDATA section. The parser passes no parameters to this event (except the user token).
content_characters

This event represents the main body of an XML document. This is the character data between element start and end tags. The parser passes the address and length of the text containing this data, which usually consists of a single string only, even if it is split across lines:

<element1>This character content is
split across two lines"</element1>

The parser also passes a flag byte which indicates if the next event provides additional characters that form part of the content. This can be true when there is a lot of data between the start and end tags.

The parser also uses the content_characters event to pass the text of CDATA sections to the application.

processing_instruction
Processing instructions (PIs) allow XML documents to contain special instructions for applications. This event occurs when the parser recognizes the name following the PI opening character sequence, <?. The event also covers the data following the PI target, up to but not including the PI closing character sequence, ?>. Trailing, but not leading white space characters in the data are included. The parser passes the address and length of the text containing the target, spread in the example, and the address and length of the text containing the data, please use real mayonnaise in the example.
comment
Occurs for any comments in the XML document. The parser passes the address and length of the text between the opening and closing comment delimiters, <!-- and -->, respectively. The only comment text in the example is This document is just an example.
namespace_declare
Occurs for any namespace declarations in the XML document. The parser passes the address and length of the namespace prefix (if any) as well as the address and length of the namespace URI. If there is no namespace prefix, the passed length is zero and the value of the address should not be used. There is no corresponding event in the PLIXSAXA and PLISAXB built-ins.
end_of_input
This event occurs whenever the parser reaches the end of the current input buffer. The parser passes (along with the BYVALUE user token) two BYADDR parameters: the address and length of the next buffer for it to process. This event and the content character events are the only events that have any BYADDR parameters, but this is the only event that has parameters that the called event should change. There is no corresponding event in the PLIXSAXA and PLISAXB built-ins, and it is this event that allows PLISAXC to parse an XML document of arbitrary size.
unresolved_reference
This event occurs for any unresolved references in the XML document. The parser passes the address and length of the unresolved reference.
unknown_attribute_reference
Occurs within attribute values for entity references other than the pre-defined entity references, listed for the event attribute_predefined_reference. The parser passes the address and length of the text containing the entity name.
exception
The parser generates this event when it detects an error processing the XML document.
Parent topic: SAX event structures


PLISAXA and PLISAXB XML Parser event function parameters

All PLISAXA and PLISAXB event functions must return a BYVALUE FIXED BIN(31) value that is a return code to the parser. For the parser to continue normally, this value should be zero.

For the first argument, the event functions pass a POINTER. This is the token value passed originally as the second argument to the built-in function.

With the following exceptions, all of the functions will also be passed a POINTER and a FIXED BIN(31) that supply the address and length of the text element for the event. The following functions and events are different:

end_of_document | No argument other than the user token is passed.
attribute_predefined_reference | In addition to the user token, one additional argument is passed: a CHAR(1) or, for a UTF-16 document, a WIDECHAR(1) that holds the value of the predefined character.
content_predefined_reference | In addition to the user token, one additional argument is passed: a CHAR(1) or, for a UTF-16 document, a WIDECHAR(1) that holds the value of the predefined character.
attribute_character_reference | In addition to the user token, one additional argument is passed: a FIXED BIN(31) that holds the value of the numeric reference.
content_character_reference | In addition to the user token, one additional argument is passed: a FIXED BIN(31) that holds the value of the numeric reference.
processing_instruction In addition to the user token, these additional arguments are passed:
  • a POINTER that is the address of the target text
  • a FIXED BIN(31) that is the length of the target text
  • a POINTER that is the address of the data text
  • a FIXED BIN(31) that is the length of the data text
exception In addition to the user token, these additional arguments are passed:
  • a POINTER that is the address of the offending text
  • a FIXED BIN(31) that is the byte offset of the offending text
  • a FIXED BIN(31) representing the value of the exception code
Parent topic: SAX event structures


PLISAXC XML Parser event function parameters

All of these functions must return a BYVALUE FIXED BIN(31) value that is a return code to the parser. If any value other than zero is returned, the parser terminates.

All of these functions are passed as the first argument a POINTER. This pointer is the token value that is passed originally as the second argument to the built-in.

With the following exceptions, all of the functions have a POINTER and a FIXED BIN(31) passed to them that provide the address and length of the text element for the event. The following functions and events are different:

start_of_document | No argument other than the user token is passed.
end_of_document | No argument other than the user token is passed.
start_of_CDATA | No argument other than the user token is passed.
end_of_CDATA | No argument other than the user token is passed.
start_of_element

In addition to the usual parameters, these additional arguments are passed.

  • a POINTER that is the address of the namespace prefix
  • a FIXED BIN(31) that is the length of the namespace prefix
  • a POINTER that is the address of the namespace URI
  • a FIXED BIN(31) that is the length of the namespace URI
end_of_element

In addition to the usual parameters, these additional arguments are passed.

  • a POINTER that is the address of the namespace prefix
  • a FIXED BIN(31) that is the length of the namespace prefix
  • a POINTER that is the address of the namespace URI
  • a FIXED BIN(31) that is the length of the namespace URI
attribute_name

In addition to the usual parameters, these additional arguments are passed.

  • a POINTER that is the address of the namespace prefix
  • a FIXED BIN(31) that is the length of the namespace prefix
  • a POINTER that is the address of the namespace URI
  • a FIXED BIN(31) that is the length of the namespace URI
namesace_declare

In addition to the user token, these additional arguments are passed.

  • a POINTER that is the address of the namespace prefix
  • a FIXED BIN(31) that is the length of the namespace prefix
  • a POINTER that is the address of the namespace URI
  • a FIXED BIN(31) that is the length of the namespace URI
content_characters In addition to the usual three parameters, a BYVALUE ALIGNED BIT(8) flag byte is passed which indicates:
  • If more content characters are in the next event. This is true if the first bit is on (if the field ANDed with '80'BX is non-null).
  • If there are no characters that need to be escaped if converted back to XML. This is true if the second bit is on(if the field ANDed with '40'BX is non-null).
end_of_input

In addition to the user token, these additional arguments are passed.

  • a POINTER that is the address of the next input buffer
  • a FIXED BIN(31) that is the length of the next input buffer
processing_instruction In addition to the user token, four additional arguments are passed:
  • a POINTER that is the address of the target text
  • a FIXED BIN(31) that is the length of the target text
  • a POINTER that is the address of the data text
  • a FIXED BIN(31) that is the length of the data text
exception In addition to the user token, three additional arguments are passed:
  • a POINTER that is the address of the offending text
  • a FIXED BIN(31) that is the return code for the exception
  • a FIXED BIN(31) that is the reason code for the exception
Parent topic: SAX event structures


XML Parser exception event error codes

There are subtle differences in how errors are handled in our parser vs. IBM's. For example, the Exception event is driven one time per character. When using the SAX Parser, the Exception event is driven one time indicating an error.

This list shows the available exception event error codes for PL/I XML parsing.

XML_ERR_OK = 0,

XML_ERR_INTERNAL_ERROR, /* 1 */

XML_ERR_NO_MEMORY, /* 2 */

XML_ERR_DOCUMENT_START, /* 3 */

XML_ERR_DOCUMENT_EMPTY, /* 4 */

XML_ERR_DOCUMENT_END, /* 5 */

XML_ERR_INVALID_HEX_CHARREF, /* 6 */

XML_ERR_INVALID_DEC_CHARREF, /* 7 */

XML_ERR_INVALID_CHARREF, /* 8 */

XML_ERR_INVALID_CHAR, /* 9 */

XML_ERR_CHARREF_AT_EOF, /* 10 */

XML_ERR_CHARREF_IN_PROLOG, /* 11 */

XML_ERR_CHARREF_IN_EPILOG, /* 12 */

XML_ERR_CHARREF_IN_DTD, /* 13 */

XML_ERR_ENTITYREF_AT_EOF, /* 14 */

XML_ERR_ENTITYREF_IN_PROLOG, /* 15 */

XML_ERR_ENTITYREF_IN_EPILOG, /* 16 */

XML_ERR_ENTITYREF_IN_DTD, /* 17 */

XML_ERR_PEREF_AT_EOF, /* 18 */

XML_ERR_PEREF_IN_PROLOG, /* 19 */

XML_ERR_PEREF_IN_EPILOG, /* 20 */

XML_ERR_PEREF_IN_INT_SUBSET, /* 21 */

XML_ERR_ENTITYREF_NO_NAME, /* 22 */

XML_ERR_ENTITYREF_SEMICOL_MISSING, /* 23 */

XML_ERR_PEREF_NO_NAME, /* 24 */

XML_ERR_PEREF_SEMICOL_MISSING, /* 25 */

XML_ERR_UNDECLARED_ENTITY, /* 26 */

XML_WAR_UNDECLARED_ENTITY, /* 27 */

XML_ERR_UNPARSED_ENTITY, /* 28 */

XML_ERR_ENTITY_IS_EXTERNAL, /* 29 */

XML_ERR_ENTITY_IS_PARAMETER, /* 30 */

XML_ERR_UNKNOWN_ENCODING, /* 31 */

XML_ERR_UNSUPPORTED_ENCODING, /* 32 */

XML_ERR_STRING_NOT_STARTED, /* 33 */

XML_ERR_STRING_NOT_CLOSED, /* 34 */

XML_ERR_NS_DECL_ERROR, /* 35 */

XML_ERR_ENTITY_NOT_STARTED, /* 36 */

XML_ERR_ENTITY_NOT_FINISHED, /* 37 */

XML_ERR_LT_IN_ATTRIBUTE, /* 38 */

XML_ERR_ATTRIBUTE_NOT_STARTED, /* 39 */

XML_ERR_ATTRIBUTE_NOT_FINISHED, /* 40 */

XML_ERR_ATTRIBUTE_WITHOUT_VALUE, /* 41 */

XML_ERR_ATTRIBUTE_REDEFINED, /* 42 */

XML_ERR_LITERAL_NOT_STARTED, /* 43 */

XML_ERR_LITERAL_NOT_FINISHED, /* 44 */

XML_ERR_COMMENT_NOT_FINISHED, /* 45 */

XML_ERR_PI_NOT_STARTED, /* 46 */

XML_ERR_PI_NOT_FINISHED, /* 47 */

XML_ERR_NOTATION_NOT_STARTED, /* 48 */

XML_ERR_NOTATION_NOT_FINISHED, /* 49 */

XML_ERR_ATTLIST_NOT_STARTED, /* 50 */

XML_ERR_ATTLIST_NOT_FINISHED, /* 51 */

XML_ERR_MIXED_NOT_STARTED, /* 52 */

XML_ERR_MIXED_NOT_FINISHED, /* 53 */

XML_ERR_ELEMCONTENT_NOT_STARTED, /* 54 */

XML_ERR_ELEMCONTENT_NOT_FINISHED, /* 55 */

XML_ERR_XMLDECL_NOT_STARTED, /* 56 */

XML_ERR_XMLDECL_NOT_FINISHED, /* 57 */

XML_ERR_CONDSEC_NOT_STARTED, /* 58 */

XML_ERR_CONDSEC_NOT_FINISHED, /* 59 */

XML_ERR_EXT_SUBSET_NOT_FINISHED, /* 60 */

XML_ERR_DOCTYPE_NOT_FINISHED, /* 61 */

XML_ERR_MISPLACED_CDATA_END, /* 62 */

XML_ERR_CDATA_NOT_FINISHED, /* 63 */

XML_ERR_RESERVED_XML_NAME, /* 64 */

XML_ERR_SPACE_REQUIRED, /* 65 */

XML_ERR_SEPARATOR_REQUIRED, /* 66 */

XML_ERR_NMTOKEN_REQUIRED, /* 67 */

XML_ERR_NAME_REQUIRED, /* 68 */

XML_ERR_PCDATA_REQUIRED, /* 69 */

XML_ERR_URI_REQUIRED, /* 70 */

XML_ERR_PUBID_REQUIRED, /* 71 */

XML_ERR_LT_REQUIRED, /* 72 */

XML_ERR_GT_REQUIRED, /* 73 */

XML_ERR_LTSLASH_REQUIRED, /* 74 */

XML_ERR_EQUAL_REQUIRED, /* 75 */

XML_ERR_TAG_NAME_MISMATCH, /* 76 */

XML_ERR_TAG_NOT_FINISHED, /* 77 */

XML_ERR_STANDALONE_VALUE, /* 78 */

XML_ERR_ENCODING_NAME, /* 79 */

XML_ERR_HYPHEN_IN_COMMENT, /* 80 */

XML_ERR_INVALID_ENCODING, /* 81 */

XML_ERR_EXT_ENTITY_STANDALONE, /* 82 */

XML_ERR_CONDSEC_INVALID, /* 83 */

XML_ERR_VALUE_REQUIRED, /* 84 */

XML_ERR_NOT_WELL_BALANCED, /* 85 */

XML_ERR_EXTRA_CONTENT, /* 86 */

XML_ERR_ENTITY_CHAR_ERROR, /* 87 */

XML_ERR_ENTITY_PE_INTERNAL, /* 88 */

XML_ERR_ENTITY_LOOP, /* 89 */

XML_ERR_ENTITY_BOUNDARY, /* 90 */

XML_ERR_INVALID_URI, /* 91 */

XML_ERR_URI_FRAGMENT, /* 92 */

XML_WAR_CATALOG_PI, /* 93 */

XML_ERR_NO_DTD, /* 94 */

XML_ERR_CONDSEC_INVALID_KEYWORD, /* 95 */

XML_ERR_VERSION_MISSING, /* 96 */

XML_WAR_UNKNOWN_VERSION, /* 97 */

XML_WAR_LANG_VALUE, /* 98 */

XML_WAR_NS_URI, /* 99 */

XML_WAR_NS_URI_RELATIVE, /* 100 */

XML_ERR_MISSING_ENCODING, /* 101 */

XML_WAR_SPACE_VALUE, /* 102 */

XML_ERR_NOT_STANDALONE, /* 103 */

XML_ERR_ENTITY_PROCESSING, /* 104 */

XML_ERR_NOTATION_PROCESSING, /* 105 */

XML_WAR_NS_COLUMN, /* 106 */

XML_WAR_ENTITY_REDEFINED, /* 107 */

XML_ERR_UNKNOWN_VERSION, /* 108 */

XML_ERR_VERSION_MISMATCH, /* 109 */

XML_NS_ERR_XML_NAMESPACE = 200,

XML_NS_ERR_UNDEFINED_NAMESPACE, /* 201 */

XML_NS_ERR_QNAME, /* 202 */

XML_NS_ERR_ATTRIBUTE_REDEFINED, /* 203 */

XML_NS_ERR_EMPTY, /* 204 */

XML_NS_ERR_COLON, /* 205 */

XML_DTD_ATTRIBUTE_DEFAULT = 500,

XML_DTD_ATTRIBUTE_REDEFINED, /* 501 */

XML_DTD_ATTRIBUTE_VALUE, /* 502 */

XML_DTD_CONTENT_ERROR, /* 503 */

XML_DTD_CONTENT_MODEL, /* 504 */

XML_DTD_CONTENT_NOT_DETERMINIST, /* 505 */

XML_DTD_DIFFERENT_PREFIX, /* 506 */

XML_DTD_ELEM_DEFAULT_NAMESPACE, /* 507 */

XML_DTD_ELEM_NAMESPACE, /* 508 */

XML_DTD_ELEM_REDEFINED, /* 509 */

XML_DTD_EMPTY_NOTATION, /* 510 */

XML_DTD_ENTITY_TYPE, /* 511 */

XML_DTD_ID_FIXED, /* 512 */

XML_DTD_ID_REDEFINED, /* 513 */

XML_DTD_ID_SUBSET, /* 514 */

XML_DTD_INVALID_CHILD, /* 515 */

XML_DTD_INVALID_DEFAULT, /* 516 */

XML_DTD_LOAD_ERROR, /* 517 */

XML_DTD_MISSING_ATTRIBUTE, /* 518 */

XML_DTD_MIXED_CORRUPT, /* 519 */

XML_DTD_MULTIPLE_ID, /* 520 */

XML_DTD_NO_DOC, /* 521 */

XML_DTD_NO_DTD, /* 522 */

XML_DTD_NO_ELEM_NAME, /* 523 */

XML_DTD_NO_PREFIX, /* 524 */

XML_DTD_NO_ROOT, /* 525 */

XML_DTD_NOTATION_REDEFINED, /* 526 */

XML_DTD_NOTATION_VALUE, /* 527 */

XML_DTD_NOT_EMPTY, /* 528 */

XML_DTD_NOT_PCDATA, /* 529 */

XML_DTD_NOT_STANDALONE, /* 530 */

XML_DTD_ROOT_NAME, /* 531 */

XML_DTD_STANDALONE_WHITE_SPACE, /* 532 */

XML_DTD_UNKNOWN_ATTRIBUTE, /* 533 */

XML_DTD_UNKNOWN_ELEM, /* 534 */

XML_DTD_UNKNOWN_ENTITY, /* 535 */

XML_DTD_UNKNOWN_ID, /* 536 */

XML_DTD_UNKNOWN_NOTATION, /* 537 */

XML_DTD_STANDALONE_DEFAULTED, /* 538 */

XML_DTD_XMLID_VALUE, /* 539 */

XML_DTD_XMLID_TYPE, /* 540 */

XML_DTD_DUP_TOKEN, /* 541 */

XML_HTML_STRUCURE_ERROR = 800,

XML_HTML_UNKNOWN_TAG, /* 801 */

XML_RNGP_ANYNAME_ATTR_ANCESTOR = 1000,

XML_RNGP_ATTR_CONFLICT, /* 1001 */

XML_RNGP_ATTRIBUTE_CHILDREN, /* 1002 */

XML_RNGP_ATTRIBUTE_CONTENT, /* 1003 */

XML_RNGP_ATTRIBUTE_EMPTY, /* 1004 */

XML_RNGP_ATTRIBUTE_NOOP, /* 1005 */

XML_RNGP_CHOICE_CONTENT, /* 1006 */

XML_RNGP_CHOICE_EMPTY, /* 1007 */

XML_RNGP_CREATE_FAILURE, /* 1008 */

XML_RNGP_DATA_CONTENT, /* 1009 */

XML_RNGP_DEF_CHOICE_AND_INTERLEAVE, /* 1010 */

XML_RNGP_DEFINE_CREATE_FAILED, /* 1011 */

XML_RNGP_DEFINE_EMPTY, /* 1012 */

XML_RNGP_DEFINE_MISSING, /* 1013 */

XML_RNGP_DEFINE_NAME_MISSING, /* 1014 */

XML_RNGP_ELEM_CONTENT_EMPTY, /* 1015 */

XML_RNGP_ELEM_CONTENT_ERROR, /* 1016 */

XML_RNGP_ELEMENT_EMPTY, /* 1017 */

XML_RNGP_ELEMENT_CONTENT, /* 1018 */

XML_RNGP_ELEMENT_NAME, /* 1019 */

XML_RNGP_ELEMENT_NO_CONTENT, /* 1020 */

XML_RNGP_ELEM_TEXT_CONFLICT, /* 1021 */

XML_RNGP_EMPTY, /* 1022 */

XML_RNGP_EMPTY_CONSTRUCT, /* 1023 */

XML_RNGP_EMPTY_CONTENT, /* 1024 */

XML_RNGP_EMPTY_NOT_EMPTY, /* 1025 */

XML_RNGP_ERROR_TYPE_LIB, /* 1026 */

XML_RNGP_EXCEPT_EMPTY, /* 1027 */

XML_RNGP_EXCEPT_MISSING, /* 1028 */

XML_RNGP_EXCEPT_MULTIPLE, /* 1029 */

XML_RNGP_EXCEPT_NO_CONTENT, /* 1030 */

XML_RNGP_EXTERNALREF_EMTPY, /* 1031 */

XML_RNGP_EXTERNAL_REF_FAILURE, /* 1032 */

XML_RNGP_EXTERNALREF_RECURSE, /* 1033 */

XML_RNGP_FORBIDDEN_ATTRIBUTE, /* 1034 */

XML_RNGP_FOREIGN_ELEMENT, /* 1035 */

XML_RNGP_GRAMMAR_CONTENT, /* 1036 */

XML_RNGP_GRAMMAR_EMPTY, /* 1037 */

XML_RNGP_GRAMMAR_MISSING, /* 1038 */

XML_RNGP_GRAMMAR_NO_START, /* 1039 */

XML_RNGP_GROUP_ATTR_CONFLICT, /* 1040 */

XML_RNGP_HREF_ERROR, /* 1041 */

XML_RNGP_INCLUDE_EMPTY, /* 1042 */

XML_RNGP_INCLUDE_FAILURE, /* 1043 */

XML_RNGP_INCLUDE_RECURSE, /* 1044 */

XML_RNGP_INTERLEAVE_ADD, /* 1045 */

XML_RNGP_INTERLEAVE_CREATE_FAILED, /* 1046 */

XML_RNGP_INTERLEAVE_EMPTY, /* 1047 */

XML_RNGP_INTERLEAVE_NO_CONTENT, /* 1048 */

XML_RNGP_INVALID_DEFINE_NAME, /* 1049 */

XML_RNGP_INVALID_URI, /* 1050 */

XML_RNGP_INVALID_VALUE, /* 1051 */

XML_RNGP_MISSING_HREF, /* 1052 */

XML_RNGP_NAME_MISSING, /* 1053 */

XML_RNGP_NEED_COMBINE, /* 1054 */

XML_RNGP_NOTALLOWED_NOT_EMPTY, /* 1055 */

XML_RNGP_NSNAME_ATTR_ANCESTOR, /* 1056 */

XML_RNGP_NSNAME_NO_NS, /* 1057 */

XML_RNGP_PARAM_FORBIDDEN, /* 1058 */

XML_RNGP_PARAM_NAME_MISSING, /* 1059 */

XML_RNGP_PARENTREF_CREATE_FAILED, /* 1060 */

XML_RNGP_PARENTREF_NAME_INVALID, /* 1061 */

XML_RNGP_PARENTREF_NO_NAME, /* 1062 */

XML_RNGP_PARENTREF_NO_PARENT, /* 1063 */

XML_RNGP_PARENTREF_NOT_EMPTY, /* 1064 */

XML_RNGP_PARSE_ERROR, /* 1065 */

XML_RNGP_PAT_ANYNAME_EXCEPT_ANYNAME, /* 1066 */

XML_RNGP_PAT_ATTR_ATTR, /* 1067 */

XML_RNGP_PAT_ATTR_ELEM, /* 1068 */

XML_RNGP_PAT_DATA_EXCEPT_ATTR, /* 1069 */

XML_RNGP_PAT_DATA_EXCEPT_ELEM, /* 1070 */

XML_RNGP_PAT_DATA_EXCEPT_EMPTY, /* 1071 */

XML_RNGP_PAT_DATA_EXCEPT_GROUP, /* 1072 */

XML_RNGP_PAT_DATA_EXCEPT_INTERLEAVE, /* 1073 */

XML_RNGP_PAT_DATA_EXCEPT_LIST, /* 1074 */

XML_RNGP_PAT_DATA_EXCEPT_ONEMORE, /* 1075 */

XML_RNGP_PAT_DATA_EXCEPT_REF, /* 1076 */

XML_RNGP_PAT_DATA_EXCEPT_TEXT, /* 1077 */

XML_RNGP_PAT_LIST_ATTR, /* 1078 */

XML_RNGP_PAT_LIST_ELEM, /* 1079 */

XML_RNGP_PAT_LIST_INTERLEAVE, /* 1080 */

XML_RNGP_PAT_LIST_LIST, /* 1081 */

XML_RNGP_PAT_LIST_REF, /* 1082 */

XML_RNGP_PAT_LIST_TEXT, /* 1083 */

XML_RNGP_PAT_NSNAME_EXCEPT_ANYNAME, /* 1084 */

XML_RNGP_PAT_NSNAME_EXCEPT_NSNAME, /* 1085 */

XML_RNGP_PAT_ONEMORE_GROUP_ATTR, /* 1086 */

XML_RNGP_PAT_ONEMORE_INTERLEAVE_ATTR, /* 1087 */

XML_RNGP_PAT_START_ATTR, /* 1088 */

XML_RNGP_PAT_START_DATA, /* 1089 */

XML_RNGP_PAT_START_EMPTY, /* 1090 */

XML_RNGP_PAT_START_GROUP, /* 1091 */

XML_RNGP_PAT_START_INTERLEAVE, /* 1092 */

XML_RNGP_PAT_START_LIST, /* 1093 */

XML_RNGP_PAT_START_ONEMORE, /* 1094 */

XML_RNGP_PAT_START_TEXT, /* 1095 */

XML_RNGP_PAT_START_VALUE, /* 1096 */

XML_RNGP_PREFIX_UNDEFINED, /* 1097 */

XML_RNGP_REF_CREATE_FAILED, /* 1098 */

XML_RNGP_REF_CYCLE, /* 1099 */

XML_RNGP_REF_NAME_INVALID, /* 1100 */

XML_RNGP_REF_NO_DEF, /* 1101 */

XML_RNGP_REF_NO_NAME, /* 1102 */

XML_RNGP_REF_NOT_EMPTY, /* 1103 */

XML_RNGP_START_CHOICE_AND_INTERLEAVE, /* 1104 */

XML_RNGP_START_CONTENT, /* 1105 */

XML_RNGP_START_EMPTY, /* 1106 */

XML_RNGP_START_MISSING, /* 1107 */

XML_RNGP_TEXT_EXPECTED, /* 1108 */

XML_RNGP_TEXT_HAS_CHILD, /* 1109 */

XML_RNGP_TYPE_MISSING, /* 1110 */

XML_RNGP_TYPE_NOT_FOUND, /* 1111 */

XML_RNGP_TYPE_VALUE, /* 1112 */

XML_RNGP_UNKNOWN_ATTRIBUTE, /* 1113 */

XML_RNGP_UNKNOWN_COMBINE, /* 1114 */

XML_RNGP_UNKNOWN_CONSTRUCT, /* 1115 */

XML_RNGP_UNKNOWN_TYPE_LIB, /* 1116 */

XML_RNGP_URI_FRAGMENT, /* 1117 */

XML_RNGP_URI_NOT_ABSOLUTE, /* 1118 */

XML_RNGP_VALUE_EMPTY, /* 1119 */

XML_RNGP_VALUE_NO_CONTENT, /* 1120 */

XML_RNGP_XMLNS_NAME, /* 1121 */

XML_RNGP_XML_NS, /* 1122 */

XML_XPATH_EXPRESSION_OK = 1200,

XML_XPATH_NUMBER_ERROR, /* 1201 */

XML_XPATH_UNFINISHED_LITERAL_ERROR, /* 1202 */

XML_XPATH_START_LITERAL_ERROR, /* 1203 */

XML_XPATH_VARIABLE_REF_ERROR, /* 1204 */

XML_XPATH_UNDEF_VARIABLE_ERROR, /* 1205 */

XML_XPATH_INVALID_PREDICATE_ERROR, /* 1206 */

XML_XPATH_EXPR_ERROR, /* 1207 */

XML_XPATH_UNCLOSED_ERROR, /* 1208 */

XML_XPATH_UNKNOWN_FUNC_ERROR, /* 1209 */

XML_XPATH_INVALID_OPERAND, /* 1210 */

XML_XPATH_INVALID_TYPE, /* 1211 */

XML_XPATH_INVALID_ARITY, /* 1212 */

XML_XPATH_INVALID_CTXT_SIZE, /* 1213 */

XML_XPATH_INVALID_CTXT_POSITION, /* 1214 */

XML_XPATH_MEMORY_ERROR, /* 1215 */

XML_XPTR_SYNTAX_ERROR, /* 1216 */

XML_XPTR_RESOURCE_ERROR, /* 1217 */

XML_XPTR_SUB_RESOURCE_ERROR, /* 1218 */

XML_XPATH_UNDEF_PREFIX_ERROR, /* 1219 */

XML_XPATH_ENCODING_ERROR, /* 1220 */

XML_XPATH_INVALID_CHAR_ERROR, /* 1221 */

XML_TREE_INVALID_HEX = 1300,

XML_TREE_INVALID_DEC, /* 1301 */

XML_TREE_UNTERMINATED_ENTITY, /* 1302 */

XML_TREE_NOT_UTF8, /* 1303 */

XML_SAVE_NOT_UTF8 = 1400,

XML_SAVE_CHAR_INVALID, /* 1401 */

XML_SAVE_NO_DOCTYPE, /* 1402 */

XML_SAVE_UNKNOWN_ENCODING, /* 1403 */

XML_REGEXP_COMPILE_ERROR = 1450,

XML_IO_UNKNOWN = 1500,

XML_IO_EACCES, /* 1501 */

XML_IO_EAGAIN, /* 1502 */

XML_IO_EBADF, /* 1503 */

XML_IO_EBADMSG, /* 1504 */

XML_IO_EBUSY, /* 1505 */

XML_IO_ECANCELED, /* 1506 */

XML_IO_ECHILD, /* 1507 */

XML_IO_EDEADLK, /* 1508 */

XML_IO_EDOM, /* 1509 */

XML_IO_EEXIST, /* 1510 */

XML_IO_EFAULT, /* 1511 */

XML_IO_EFBIG, /* 1512 */

XML_IO_EINPROGRESS, /* 1513 */

XML_IO_EINTR, /* 1514 */

XML_IO_EINVAL, /* 1515 */

XML_IO_EIO, /* 1516 */

XML_IO_EISDIR, /* 1517 */

XML_IO_EMFILE, /* 1518 */

XML_IO_EMLINK, /* 1519 */

XML_IO_EMSGSIZE, /* 1520 */

XML_IO_ENAMETOOLONG, /* 1521 */

XML_IO_ENFILE, /* 1522 */

XML_IO_ENODEV, /* 1523 */

XML_IO_ENOENT, /* 1524 */

XML_IO_ENOEXEC, /* 1525 */

XML_IO_ENOLCK, /* 1526 */

XML_IO_ENOMEM, /* 1527 */

XML_IO_ENOSPC, /* 1528 */

XML_IO_ENOSYS, /* 1529 */

XML_IO_ENOTDIR, /* 1530 */

XML_IO_ENOTEMPTY, /* 1531 */

XML_IO_ENOTSUP, /* 1532 */

XML_IO_ENOTTY, /* 1533 */

XML_IO_ENXIO, /* 1534 */

XML_IO_EPERM, /* 1535 */

XML_IO_EPIPE, /* 1536 */

XML_IO_ERANGE, /* 1537 */

XML_IO_EROFS, /* 1538 */

XML_IO_ESPIPE, /* 1539 */

XML_IO_ESRCH, /* 1540 */

XML_IO_ETIMEDOUT, /* 1541 */

XML_IO_EXDEV, /* 1542 */

XML_IO_NETWORK_ATTEMPT, /* 1543 */

XML_IO_ENCODER, /* 1544 */

XML_IO_FLUSH, /* 1545 */

XML_IO_WRITE, /* 1546 */

XML_IO_NO_INPUT, /* 1547 */

XML_IO_BUFFER_FULL, /* 1548 */

XML_IO_LOAD_ERROR, /* 1549 */

XML_IO_ENOTSOCK, /* 1550 */

XML_IO_EISCONN, /* 1551 */

XML_IO_ECONNREFUSED, /* 1552 */

XML_IO_ENETUNREACH, /* 1553 */

XML_IO_EADDRINUSE, /* 1554 */

XML_IO_EALREADY, /* 1555 */

XML_IO_EAFNOSUPPORT, /* 1556 */

XML_XINCLUDE_RECURSION=1600,

XML_XINCLUDE_PARSE_VALUE, /* 1601 */

XML_XINCLUDE_ENTITY_DEF_MISMATCH, /* 1602 */

XML_XINCLUDE_NO_HREF, /* 1603 */

XML_XINCLUDE_NO_FALLBACK, /* 1604 */

XML_XINCLUDE_HREF_URI, /* 1605 */

XML_XINCLUDE_TEXT_FRAGMENT, /* 1606 */

XML_XINCLUDE_TEXT_DOCUMENT, /* 1607 */

XML_XINCLUDE_INVALID_CHAR, /* 1608 */

XML_XINCLUDE_BUILD_FAILED, /* 1609 */

XML_XINCLUDE_UNKNOWN_ENCODING, /* 1610 */

XML_XINCLUDE_MULTIPLE_ROOT, /* 1611 */

XML_XINCLUDE_XPTR_FAILED, /* 1612 */

XML_XINCLUDE_XPTR_RESULT, /* 1613 */

XML_XINCLUDE_INCLUDE_IN_INCLUDE, /* 1614 */

XML_XINCLUDE_FALLBACKS_IN_INCLUDE, /* 1615 */

XML_XINCLUDE_FALLBACK_NOT_IN_INCLUDE, /* 1616 */

XML_XINCLUDE_DEPRECATED_NS, /* 1617 */

XML_XINCLUDE_FRAGMENT_ID, /* 1618 */

XML_CATALOG_MISSING_ATTR = 1650,

XML_CATALOG_ENTRY_BROKEN, /* 1651 */

XML_CATALOG_PREFER_VALUE, /* 1652 */

XML_CATALOG_NOT_CATALOG, /* 1653 */

XML_CATALOG_RECURSION, /* 1654 */

XML_SCHEMAP_PREFIX_UNDEFINED = 1700,

XML_SCHEMAP_ATTRFORMDEFAULT_VALUE, /* 1701 */

XML_SCHEMAP_ATTRGRP_NONAME_NOREF, /* 1702 */

XML_SCHEMAP_ATTR_NONAME_NOREF, /* 1703 */

XML_SCHEMAP_COMPLEXTYPE_NONAME_NOREF, /* 1704 */

XML_SCHEMAP_ELEMFORMDEFAULT_VALUE, /* 1705 */

XML_SCHEMAP_ELEM_NONAME_NOREF, /* 1706 */

XML_SCHEMAP_EXTENSION_NO_BASE, /* 1707 */

XML_SCHEMAP_FACET_NO_VALUE, /* 1708 */

XML_SCHEMAP_FAILED_BUILD_IMPORT, /* 1709 */

XML_SCHEMAP_GROUP_NONAME_NOREF, /* 1710 */

XML_SCHEMAP_IMPORT_NAMESPACE_NOT_URI, /* 1711 */

XML_SCHEMAP_IMPORT_REDEFINE_NSNAME, /* 1712 */

XML_SCHEMAP_IMPORT_SCHEMA_NOT_URI, /* 1713 */

XML_SCHEMAP_INVALID_BOOLEAN, /* 1714 */

XML_SCHEMAP_INVALID_ENUM, /* 1715 */

XML_SCHEMAP_INVALID_FACET, /* 1716 */

XML_SCHEMAP_INVALID_FACET_VALUE, /* 1717 */

XML_SCHEMAP_INVALID_MAXOCCURS, /* 1718 */

XML_SCHEMAP_INVALID_MINOCCURS, /* 1719 */

XML_SCHEMAP_INVALID_REF_AND_SUBTYPE, /* 1720 */

XML_SCHEMAP_INVALID_WHITE_SPACE, /* 1721 */

XML_SCHEMAP_NOATTR_NOREF, /* 1722 */

XML_SCHEMAP_NOTATION_NO_NAME, /* 1723 */

XML_SCHEMAP_NOTYPE_NOREF, /* 1724 */

XML_SCHEMAP_REF_AND_SUBTYPE, /* 1725 */

XML_SCHEMAP_RESTRICTION_NONAME_NOREF, /* 1726 */

XML_SCHEMAP_SIMPLETYPE_NONAME, /* 1727 */

XML_SCHEMAP_TYPE_AND_SUBTYPE, /* 1728 */

XML_SCHEMAP_UNKNOWN_ALL_CHILD, /* 1729 */

XML_SCHEMAP_UNKNOWN_ANYATTRIBUTE_CHILD, /* 1730 */

XML_SCHEMAP_UNKNOWN_ATTR_CHILD, /* 1731 */

XML_SCHEMAP_UNKNOWN_ATTRGRP_CHILD, /* 1732 */

XML_SCHEMAP_UNKNOWN_ATTRIBUTE_GROUP, /* 1733 */

XML_SCHEMAP_UNKNOWN_BASE_TYPE, /* 1734 */

XML_SCHEMAP_UNKNOWN_CHOICE_CHILD, /* 1735 */

XML_SCHEMAP_UNKNOWN_COMPLEXCONTENT_CHILD, /* 1736 */

XML_SCHEMAP_UNKNOWN_COMPLEXTYPE_CHILD, /* 1737 */

XML_SCHEMAP_UNKNOWN_ELEM_CHILD, /* 1738 */

XML_SCHEMAP_UNKNOWN_EXTENSION_CHILD, /* 1739 */

XML_SCHEMAP_UNKNOWN_FACET_CHILD, /* 1740 */

XML_SCHEMAP_UNKNOWN_FACET_TYPE, /* 1741 */

XML_SCHEMAP_UNKNOWN_GROUP_CHILD, /* 1742 */

XML_SCHEMAP_UNKNOWN_IMPORT_CHILD, /* 1743 */

XML_SCHEMAP_UNKNOWN_LIST_CHILD, /* 1744 */

XML_SCHEMAP_UNKNOWN_NOTATION_CHILD, /* 1745 */

XML_SCHEMAP_UNKNOWN_PROCESSCONTENT_CHILD, /* 1746 */

XML_SCHEMAP_UNKNOWN_REF, /* 1747 */

XML_SCHEMAP_UNKNOWN_RESTRICTION_CHILD, /* 1748 */

XML_SCHEMAP_UNKNOWN_SCHEMAS_CHILD, /* 1749 */

XML_SCHEMAP_UNKNOWN_SEQUENCE_CHILD, /* 1750 */

XML_SCHEMAP_UNKNOWN_SIMPLECONTENT_CHILD, /* 1751 */

XML_SCHEMAP_UNKNOWN_SIMPLETYPE_CHILD, /* 1752 */

XML_SCHEMAP_UNKNOWN_TYPE, /* 1753 */

XML_SCHEMAP_UNKNOWN_UNION_CHILD, /* 1754 */

XML_SCHEMAP_ELEM_DEFAULT_FIXED, /* 1755 */

XML_SCHEMAP_REGEXP_INVALID, /* 1756 */

XML_SCHEMAP_FAILED_LOAD, /* 1757 */

XML_SCHEMAP_NOTHING_TO_PARSE, /* 1758 */

XML_SCHEMAP_NOROOT, /* 1759 */

XML_SCHEMAP_REDEFINED_GROUP, /* 1760 */

XML_SCHEMAP_REDEFINED_TYPE, /* 1761 */

XML_SCHEMAP_REDEFINED_ELEMENT, /* 1762 */

XML_SCHEMAP_REDEFINED_ATTRGROUP, /* 1763 */

XML_SCHEMAP_REDEFINED_ATTR, /* 1764 */

XML_SCHEMAP_REDEFINED_NOTATION, /* 1765 */

XML_SCHEMAP_FAILED_PARSE, /* 1766 */

XML_SCHEMAP_UNKNOWN_PREFIX, /* 1767 */

XML_SCHEMAP_DEF_AND_PREFIX, /* 1768 */

XML_SCHEMAP_UNKNOWN_INCLUDE_CHILD, /* 1769 */

XML_SCHEMAP_INCLUDE_SCHEMA_NOT_URI, /* 1770 */

XML_SCHEMAP_INCLUDE_SCHEMA_NO_URI, /* 1771 */

XML_SCHEMAP_NOT_SCHEMA, /* 1772 */

XML_SCHEMAP_UNKNOWN_MEMBER_TYPE, /* 1773 */

XML_SCHEMAP_INVALID_ATTR_USE, /* 1774 */

XML_SCHEMAP_RECURSIVE, /* 1775 */

XML_SCHEMAP_SUPERNUMEROUS_LIST_ITEM_TYPE, /* 1776 */

XML_SCHEMAP_INVALID_ATTR_COMBINATION, /* 1777 */

XML_SCHEMAP_INVALID_ATTR_INLINE_COMBINATION, /* 1778 */

XML_SCHEMAP_MISSING_SIMPLETYPE_CHILD, /* 1779 */

XML_SCHEMAP_INVALID_ATTR_NAME, /* 1780 */

XML_SCHEMAP_REF_AND_CONTENT, /* 1781 */

XML_SCHEMAP_CT_PROPS_CORRECT_1, /* 1782 */

XML_SCHEMAP_CT_PROPS_CORRECT_2, /* 1783 */

XML_SCHEMAP_CT_PROPS_CORRECT_3, /* 1784 */

XML_SCHEMAP_CT_PROPS_CORRECT_4, /* 1785 */

XML_SCHEMAP_CT_PROPS_CORRECT_5, /* 1786 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_1, /* 1787 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_2_1_1, /* 1788 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_2_1_2, /* 1789 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_2_2, /* 1790 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_3, /* 1791 */

XML_SCHEMAP_WILDCARD_INVALID_NS_MEMBER, /* 1792 */

XML_SCHEMAP_INTERSECTION_NOT_EXPRESSIBLE, /* 1793 */

XML_SCHEMAP_UNION_NOT_EXPRESSIBLE, /* 1794 */

XML_SCHEMAP_SRC_IMPORT_3_1, /* 1795 */

XML_SCHEMAP_SRC_IMPORT_3_2, /* 1796 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_4_1, /* 1797 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_4_2, /* 1798 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_4_3, /* 1799 */

XML_SCHEMAP_COS_CT_EXTENDS_1_3, /* 1800 */

XML_SCHEMAV_NOROOT = 1801,

XML_SCHEMAV_UNDECLAREDELEM, /* 1802 */

XML_SCHEMAV_NOTTOPLEVEL, /* 1803 */

XML_SCHEMAV_MISSING, /* 1804 */

XML_SCHEMAV_WRONGELEM, /* 1805 */

XML_SCHEMAV_NOTYPE, /* 1806 */

XML_SCHEMAV_NOROLLBACK, /* 1807 */

XML_SCHEMAV_ISABSTRACT, /* 1808 */

XML_SCHEMAV_NOTEMPTY, /* 1809 */

XML_SCHEMAV_ELEMCONT, /* 1810 */

XML_SCHEMAV_HAVEDEFAULT, /* 1811 */

XML_SCHEMAV_NOTNILLABLE, /* 1812 */

XML_SCHEMAV_EXTRACONTENT, /* 1813 */

XML_SCHEMAV_INVALIDATTR, /* 1814 */

XML_SCHEMAV_INVALIDELEM, /* 1815 */

XML_SCHEMAV_NOTDETERMINIST, /* 1816 */

XML_SCHEMAV_CONSTRUCT, /* 1817 */

XML_SCHEMAV_INTERNAL, /* 1818 */

XML_SCHEMAV_NOTSIMPLE, /* 1819 */

XML_SCHEMAV_ATTRUNKNOWN, /* 1820 */

XML_SCHEMAV_ATTRINVALID, /* 1821 */

XML_SCHEMAV_VALUE, /* 1822 */

XML_SCHEMAV_FACET, /* 1823 */

XML_SCHEMAV_CVC_DATATYPE_VALID_1_2_1, /* 1824 */

XML_SCHEMAV_CVC_DATATYPE_VALID_1_2_2, /* 1825 */

XML_SCHEMAV_CVC_DATATYPE_VALID_1_2_3, /* 1826 */

XML_SCHEMAV_CVC_TYPE_3_1_1, /* 1827 */

XML_SCHEMAV_CVC_TYPE_3_1_2, /* 1828 */

XML_SCHEMAV_CVC_FACET_VALID, /* 1829 */

XML_SCHEMAV_CVC_LENGTH_VALID, /* 1830 */

XML_SCHEMAV_CVC_MINLENGTH_VALID, /* 1831 */

XML_SCHEMAV_CVC_MAXLENGTH_VALID, /* 1832 */

XML_SCHEMAV_CVC_MININCLUSIVE_VALID, /* 1833 */

XML_SCHEMAV_CVC_MAXINCLUSIVE_VALID, /* 1834 */

XML_SCHEMAV_CVC_MINEXCLUSIVE_VALID, /* 1835 */

XML_SCHEMAV_CVC_MAXEXCLUSIVE_VALID, /* 1836 */

XML_SCHEMAV_CVC_TOTALDIGITS_VALID, /* 1837 */

XML_SCHEMAV_CVC_FRACTIONDIGITS_VALID, /* 1838 */

XML_SCHEMAV_CVC_PATTERN_VALID, /* 1839 */

XML_SCHEMAV_CVC_ENUMERATION_VALID, /* 1840 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_2_1, /* 1841 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_2_2, /* 1842 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_2_3, /* 1843 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_2_4, /* 1844 */

XML_SCHEMAV_CVC_ELT_1, /* 1845 */

XML_SCHEMAV_CVC_ELT_2, /* 1846 */

XML_SCHEMAV_CVC_ELT_3_1, /* 1847 */

XML_SCHEMAV_CVC_ELT_3_2_1, /* 1848 */

XML_SCHEMAV_CVC_ELT_3_2_2, /* 1849 */

XML_SCHEMAV_CVC_ELT_4_1, /* 1850 */

XML_SCHEMAV_CVC_ELT_4_2, /* 1851 */

XML_SCHEMAV_CVC_ELT_4_3, /* 1852 */

XML_SCHEMAV_CVC_ELT_5_1_1, /* 1853 */

XML_SCHEMAV_CVC_ELT_5_1_2, /* 1854 */

XML_SCHEMAV_CVC_ELT_5_2_1, /* 1855 */

XML_SCHEMAV_CVC_ELT_5_2_2_1, /* 1856 */

XML_SCHEMAV_CVC_ELT_5_2_2_2_1, /* 1857 */

XML_SCHEMAV_CVC_ELT_5_2_2_2_2, /* 1858 */

XML_SCHEMAV_CVC_ELT_6, /* 1859 */

XML_SCHEMAV_CVC_ELT_7, /* 1860 */

XML_SCHEMAV_CVC_ATTRIBUTE_1, /* 1861 */

XML_SCHEMAV_CVC_ATTRIBUTE_2, /* 1862 */

XML_SCHEMAV_CVC_ATTRIBUTE_3, /* 1863 */

XML_SCHEMAV_CVC_ATTRIBUTE_4, /* 1864 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_3_1, /* 1865 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_3_2_1, /* 1866 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_3_2_2, /* 1867 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_4, /* 1868 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_5_1, /* 1869 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_5_2, /* 1870 */

XML_SCHEMAV_ELEMENT_CONTENT, /* 1871 */

XML_SCHEMAV_DOCUMENT_ELEMENT_MISSING, /* 1872 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_1, /* 1873 */

XML_SCHEMAV_CVC_AU, /* 1874 */

XML_SCHEMAV_CVC_TYPE_1, /* 1875 */

XML_SCHEMAV_CVC_TYPE_2, /* 1876 */

XML_SCHEMAV_CVC_IDC, /* 1877 */

XML_SCHEMAV_CVC_WILDCARD, /* 1878 */

XML_SCHEMAV_MISC, /* 1879 */

XML_XPTR_UNKNOWN_SCHEME = 1900,

XML_XPTR_CHILDSEQ_START, /* 1901 */

XML_XPTR_EVAL_FAILED, /* 1902 */

XML_XPTR_EXTRA_OBJECTS, /* 1903 */

XML_C14N_CREATE_CTXT = 1950,

XML_C14N_REQUIRES_UTF8, /* 1951 */

XML_C14N_CREATE_STACK, /* 1952 */

XML_C14N_INVALID_NODE, /* 1953 */

XML_C14N_UNKNOWN_NODE, /* 1954 */

XML_C14N_RELATIVE_NAMESPACE, /* 1955 */

XML_FTP_PASV_ANSWER = 2000,

XML_FTP_EPSV_ANSWER, /* 2001 */

XML_FTP_ACCNT, /* 2002 */

XML_FTP_URL_SYNTAX, /* 2003 */

XML_HTTP_URL_SYNTAX = 2020,

XML_HTTP_USE_IP, /* 2021 */

XML_HTTP_UNKNOWN_HOST, /* 2022 */

XML_SCHEMAP_SRC_SIMPLE_TYPE_1 = 3000,

XML_SCHEMAP_SRC_SIMPLE_TYPE_2, /* 3001 */

XML_SCHEMAP_SRC_SIMPLE_TYPE_3, /* 3002 */

XML_SCHEMAP_SRC_SIMPLE_TYPE_4, /* 3003 */

XML_SCHEMAP_SRC_RESOLVE, /* 3004 */

XML_SCHEMAP_SRC_RESTRICTION_BASE_OR_SIMPLETYPE, /* 3005 */

XML_SCHEMAP_SRC_LIST_ITEMTYPE_OR_SIMPLETYPE, /* 3006 */

XML_SCHEMAP_SRC_UNION_MEMBERTYPES_OR_SIMPLETYPES, /* 3007 */

XML_SCHEMAP_ST_PROPS_CORRECT_1, /* 3008 */

XML_SCHEMAP_ST_PROPS_CORRECT_2, /* 3009 */

XML_SCHEMAP_ST_PROPS_CORRECT_3, /* 3010 */

XML_SCHEMAP_COS_ST_RESTRICTS_1_1, /* 3011 */

XML_SCHEMAP_COS_ST_RESTRICTS_1_2, /* 3012 */

XML_SCHEMAP_COS_ST_RESTRICTS_1_3_1, /* 3013 */

XML_SCHEMAP_COS_ST_RESTRICTS_1_3_2, /* 3014 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_1, /* 3015 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_3_1_1, /* 3016 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_3_1_2, /* 3017 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_3_2_1, /* 3018 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_3_2_2, /* 3019 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_3_2_3, /* 3020 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_3_2_4, /* 3021 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_3_2_5, /* 3022 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_1, /* 3023 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_3_1, /* 3024 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_3_1_2, /* 3025 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_3_2_2, /* 3026 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_3_2_1, /* 3027 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_3_2_3, /* 3028 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_3_2_4, /* 3029 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_3_2_5, /* 3030 */

XML_SCHEMAP_COS_ST_DERIVED_OK_2_1, /* 3031 */

XML_SCHEMAP_COS_ST_DERIVED_OK_2_2, /* 3032 */

XML_SCHEMAP_S4S_ELEM_NOT_ALLOWED, /* 3033 */

XML_SCHEMAP_S4S_ELEM_MISSING, /* 3034 */

XML_SCHEMAP_S4S_ATTR_NOT_ALLOWED, /* 3035 */

XML_SCHEMAP_S4S_ATTR_MISSING, /* 3036 */

XML_SCHEMAP_S4S_ATTR_INVALID_VALUE, /* 3037 */

XML_SCHEMAP_SRC_ELEMENT_1, /* 3038 */

XML_SCHEMAP_SRC_ELEMENT_2_1, /* 3039 */

XML_SCHEMAP_SRC_ELEMENT_2_2, /* 3040 */

XML_SCHEMAP_SRC_ELEMENT_3, /* 3041 */

XML_SCHEMAP_P_PROPS_CORRECT_1, /* 3042 */

XML_SCHEMAP_P_PROPS_CORRECT_2_1, /* 3043 */

XML_SCHEMAP_P_PROPS_CORRECT_2_2, /* 3044 */

XML_SCHEMAP_E_PROPS_CORRECT_2, /* 3045 */

XML_SCHEMAP_E_PROPS_CORRECT_3, /* 3046 */

XML_SCHEMAP_E_PROPS_CORRECT_4, /* 3047 */

XML_SCHEMAP_E_PROPS_CORRECT_5, /* 3048 */

XML_SCHEMAP_E_PROPS_CORRECT_6, /* 3049 */

XML_SCHEMAP_SRC_INCLUDE, /* 3050 */

XML_SCHEMAP_SRC_ATTRIBUTE_1, /* 3051 */

XML_SCHEMAP_SRC_ATTRIBUTE_2, /* 3052 */

XML_SCHEMAP_SRC_ATTRIBUTE_3_1, /* 3053 */

XML_SCHEMAP_SRC_ATTRIBUTE_3_2, /* 3054 */

XML_SCHEMAP_SRC_ATTRIBUTE_4, /* 3055 */

XML_SCHEMAP_NO_XMLNS, /* 3056 */

XML_SCHEMAP_NO_XSI, /* 3057 */

XML_SCHEMAP_COS_VALID_DEFAULT_1, /* 3058 */

XML_SCHEMAP_COS_VALID_DEFAULT_2_1, /* 3059 */

XML_SCHEMAP_COS_VALID_DEFAULT_2_2_1, /* 3060 */

XML_SCHEMAP_COS_VALID_DEFAULT_2_2_2, /* 3061 */

XML_SCHEMAP_CVC_SIMPLE_TYPE, /* 3062 */

XML_SCHEMAP_COS_CT_EXTENDS_1_1, /* 3063 */

XML_SCHEMAP_SRC_IMPORT_1_1, /* 3064 */

XML_SCHEMAP_SRC_IMPORT_1_2, /* 3065 */

XML_SCHEMAP_SRC_IMPORT_2, /* 3066 */

XML_SCHEMAP_SRC_IMPORT_2_1, /* 3067 */

XML_SCHEMAP_SRC_IMPORT_2_2, /* 3068 */

XML_SCHEMAP_INTERNAL, /* 3069 non-W3C */

XML_SCHEMAP_NOT_DETERMINISTIC, /* 3070 non-W3C */

XML_SCHEMAP_SRC_ATTRIBUTE_GROUP_1, /* 3071 */

XML_SCHEMAP_SRC_ATTRIBUTE_GROUP_2, /* 3072 */

XML_SCHEMAP_SRC_ATTRIBUTE_GROUP_3, /* 3073 */

XML_SCHEMAP_MG_PROPS_CORRECT_1, /* 3074 */

XML_SCHEMAP_MG_PROPS_CORRECT_2, /* 3075 */

XML_SCHEMAP_SRC_CT_1, /* 3076 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_2_1_3, /* 3077 */

XML_SCHEMAP_AU_PROPS_CORRECT_2, /* 3078 */

XML_SCHEMAP_A_PROPS_CORRECT_2, /* 3079 */

XML_SCHEMAP_C_PROPS_CORRECT, /* 3080 */

XML_SCHEMAP_SRC_REDEFINE, /* 3081 */

XML_SCHEMAP_SRC_IMPORT, /* 3082 */

XML_SCHEMAP_WARN_SKIP_SCHEMA, /* 3083 */

XML_SCHEMAP_WARN_UNLOCATED_SCHEMA, /* 3084 */

XML_SCHEMAP_WARN_ATTR_REDECL_PROH, /* 3085 */

XML_SCHEMAP_WARN_ATTR_POINTLESS_PROH, /* 3085 */

XML_SCHEMAP_AG_PROPS_CORRECT, /* 3086 */

XML_SCHEMAP_COS_CT_EXTENDS_1_2, /* 3087 */

XML_SCHEMAP_AU_PROPS_CORRECT, /* 3088 */

XML_SCHEMAP_A_PROPS_CORRECT_3, /* 3089 */

XML_SCHEMAP_COS_ALL_LIMITED, /* 3090 */

XML_SCHEMATRONV_ASSERT = 4000, /* 4000 */

XML_SCHEMATRONV_REPORT,

XML_MODULE_OPEN = 4900, /* 4900 */

XML_MODULE_CLOSE, /* 4901 */

XML_CHECK_FOUND_ELEMENT = 5000,

XML_CHECK_FOUND_ATTRIBUTE, /* 5001 */

XML_CHECK_FOUND_TEXT, /* 5002 */

XML_CHECK_FOUND_CDATA, /* 5003 */

XML_CHECK_FOUND_ENTITYREF, /* 5004 */

XML_CHECK_FOUND_ENTITY, /* 5005 */

XML_CHECK_FOUND_PI, /* 5006 */

XML_CHECK_FOUND_COMMENT, /* 5007 */

XML_CHECK_FOUND_DOCTYPE, /* 5008 */

XML_CHECK_FOUND_FRAGMENT, /* 5009 */

XML_CHECK_FOUND_NOTATION, /* 5010 */

XML_CHECK_UNKNOWN_NODE, /* 5011 */

XML_CHECK_ENTITY_TYPE, /* 5012 */

XML_CHECK_NO_PARENT, /* 5013 */

XML_CHECK_NO_DOC, /* 5014 */

XML_CHECK_NO_NAME, /* 5015 */

XML_CHECK_NO_ELEM, /* 5016 */

XML_CHECK_WRONG_DOC, /* 5017 */

XML_CHECK_NO_PREV, /* 5018 */

XML_CHECK_WRONG_PREV, /* 5019 */

XML_CHECK_NO_NEXT, /* 5020 */

XML_CHECK_WRONG_NEXT, /* 5021 */

XML_CHECK_NOT_DTD, /* 5022 */

XML_CHECK_NOT_ATTR, /* 5023 */

XML_CHECK_NOT_ATTR_DECL, /* 5024 */

XML_CHECK_NOT_ELEM_DECL, /* 5025 */

XML_CHECK_NOT_ENTITY_DECL, /* 5026 */

XML_CHECK_NOT_NS_DECL, /* 5027 */

XML_CHECK_NO_HREF, /* 5028 */

XML_CHECK_WRONG_PARENT,/* 5029 */

XML_CHECK_NS_SCOPE, /* 5030 */

XML_CHECK_NS_ANCESTOR, /* 5031 */

XML_CHECK_NOT_UTF8, /* 5032 */

XML_CHECK_NO_DICT, /* 5033 */

XML_CHECK_NOT_NCNAME, /* 5034 */

XML_CHECK_OUTSIDE_DICT, /* 5035 */

XML_CHECK_WRONG_NAME, /* 5036 */

XML_CHECK_NAME_NOT_NULL, /* 5037 */

XML_I18N_NO_NAME = 6000,

XML_I18N_NO_HANDLER, /* 6001 */

XML_I18N_EXCESS_HANDLER, /* 6002 */

XML_I18N_CONV_FAILED, /* 6003 */

XML_I18N_NO_OUTPUT /* 6004 */

Parent topic: SAX event structures


PLISAXA and PLISAXB event structure example

This shows an example of a SAX event structure for PLISAXA and PLISAXB.

saxtest: proc options( main );

    dcl
      1 eventhandler /* static  */

        ,2 e01 type event
               init( start_of_document )
        ,2 e02 type event
               init( version_information )
        ,2 e03 type event
               init( encoding_declaration )
        ,2 e04 type event
               init( standalone_declaration )
        ,2 e05 type event
               init( document_type_declaration )
        ,2 e06 type event_end_of_document
               init( end_of_document )
        ,2 e07 type event
               init( start_of_element )
        ,2 e08 type event
               init( attribute_name )
        ,2 e09 type event
               init( attribute_characters )
        ,2 e10 type event_predefined_ref
               init( attribute_predefined_reference )
        ,2 e11 type event_character_ref
               init( attribute_character_reference )
        ,2 e12 type event
               init( end_of_element )
        ,2 e13 type event
               init( start_of_cdata )
        ,2 e14 type event
               init( end_of_cdata )
        ,2 e15 type event
               init( content_characters )
        ,2 e16 type event_predefined_ref
               init( content_predefined_reference )
        ,2 e17 type event_character_ref
               init( content_character_reference )
        ,2 e18 type event_pi
               init( processing_instruction )
        ,2 e19 type event
               init( comment )
        ,2 e20 type event
               init( unknown_attribute_reference )
        ,2 e21 type event
               init( unknown_content_reference )
        ,2 e22 type event
               init( start_of_prefix_mapping )
        ,2 e23 type event
               init( end_of_prefix_mapping )
        ,2 e24 type event_exception
               init( exception )
        ;
Parent topic: SAX event structures


PLISAXC event structure example

This shows an example of a SAX event structure for PLISAXC.

This shows an example of a SAX event structure for PLISAXA and PLISAXB.

saxtest: proc options( main );

// eventHandler for PLISAXC
  dcl
    1 eventHandler_c

      ,2 e01 type event_without_data
              init( start_of_document )
      ,2 e02 type event
              init( version_information )
      ,2 e03 type event
              init( encoding_declaration )
      ,2 e04 type event
             init( standalone_declaration )
      ,2 e05 type event
             init( document_type_declaration )
      ,2 e06 type event_without_data
             init( end_of_document )
      ,2 e07 type event_with_namespace
             init( start_of_element )
      ,2 e08 type event_with_namespace
             init( attribute_name )
      ,2 e09 type event
             init( attribute_characters )
      ,2 e10 type event_with_namespace
             init( end_of_element )
      ,2 e11 type event_without_data
             init( start_of_cdata )
      ,2 e12 type event_without_data
             init( end_of_cdata )
      ,2 e13 type event_with_flag
             init( content_characters )
      ,2 e14 type event_pi
             init( processing_instruction )
      ,2 e15 type event
             init( comment )
      ,2 e16 type event_namespace_dcl
             init( namespace_declare )
      ,2 e17 type event_end_of_input
             init( end_of_input )
      ,2 e18 type event
             init( unresolved_reference )
      ,2 e19 type event_exception
             init( exception )
      ;
Parent topic: SAX event structures


Event differences

These events are part of the PLISAXA and PLISAXB event structure, but are not in PLISAXC:

  • attribute_predefined_reference
  • attribute_character_reference
  • content_predefined_reference
  • content_character_reference
  • unknown_attribute_reference
  • unknown_content_reference
  • start_of_prefix_mapping
  • end_of_prefix_mapping

These events are not part of the PLISAXA and PLISAXB event structure, but are in PLISAXC:

  • namespace_declare
  • unresolved_reference
  • end_of_input

These events are common to PLISAXA/PLISAXB and PLISAXC, but different parameters are passed to PLISAXA/PLISAXB than are passed to PLISAXC:

start_of_document
No parameters are passed.
start_of_element
With PLISAXC, namespace data is also passed.
end_of_element
With PLISAXC, namespace data is also passed.
attribute_name
With PLISAXC, namespace data is also passed.
content_characters
With PLISAXC, a flag byte is also passed.
exception
With PLISAXC, a return and reason code is passed instead of an error id.
start_of_cdata
No parameters are passed.
start_of_cdata
No parameters are passed.
Parent topic: SAX event structures


XML document coded character sets

The PLISAX built-in subroutines only work with XML documents in WIDECHAR encoded using Unicode UTF-16, or in CHARACTER encoded using one certain supported single-byte character sets. The parser uses up to three sources of information about the encoding of your XML document, and signals an exception XML event if it discovers any conflicts between these sources:

  • The parser determines the basic encoding of a document by inspecting its initial characters.
  • If the previous step succeeds, the parser then looks for any encoding declaration.
  • Finally, it refers to the codepage value on the applicable PLISAX built-in call.

If the XML document begins with an XML declaration that includes an encoding declaration specifying one of the supported code pages listed below, the parser honors the encoding declaration if it does not conflict with either the basic document encoding or the encoding information from the PLISAX built-in. If the XML document does not have an XML declaration at all, or if the XML declaration omits the encoding declaration, the parser uses the encoding information from the PLISAX built-in to process the document, as long as it does not conflict with the basic document encoding.

  • Supported EBCDIC and ASCII code pages
  • Specifying a code page
Parent topic: XML Parser Support in PL/I


Supported EBCDIC and ASCII code pages

EBCDIC

This table shows the supported EBCDIC code pages. In each row, the first number is the Euro Country Extended Code Page (ECECP), the second number is the Country Extended Code Page (CECP).

CCSID | Code Page Locale/Description
01208 | Unicode UTF-8 (PLISAXC only)
01047 | Latin 1 / Open Systems
01140, 00037 | USA, Canada, etc.
01141, 00273 | Austria, Germany
01142, 00277 | Denmark, Norway
01143, 00278 | Finland, Sweden
01144, 00280 | Italy
01145, 00284 | Spain, Latin America (Spanish)
01146, 00285 | UK
01147, 00297 | France
01148, 00500 | International
01149, 00871 | Iceland

ASCII (PLISAXA and PLISAXB only)

This table shows the supported ASCII code pages.

CCSID | Code Page Locale/Description
00813 | ISO 8859-7 Greek / Latin
00819 | ISO 8859-1 Latin 1 / Open Systems
00920 | ISO 8859-9 Latin 5 (ECMA-128, Turkey TS-5881)
Parent topic: XML document coded character sets


Specifying a code page

If your document does not include an encoding declaration in the XML declaration, or does not have an XML declaration at all, the parser uses the encoding information provided by the PLISAX built-in call in conjunction with the basic encoding of the document.

You can also specify the encoding information for the document in the XML declaration, with which most XML documents begin. An example of an XML declaration that includes an encoding declaration is:

<xml version="1.0" encoding="ibm-1140">

If your XML document includes an encoding declaration, ensure that it is consistent with the encoding information provided by the PLISAX built-in and with the basic encoding of the document. If there is any conflict between the encoding declaration, the encoding information provided by the PLISAX built-ins and the basic encoding of the document, the parser signals an exception XML event.

Specify the encoding declaration as follows:

Using a number

You can specify the CCSID number (with or without any number of leading zeroes), prefixed by any of the following (in any mixture of upper or lower case):

IBM_ | CP | CCSID_
IBM- | CP_ | CCSID-
 | CP- |

Using an alias

You can use any of the following supported aliases (in any mixture of lower and upper case):

Code Page | Aliases
037 | EBCDIC-CP-US, EBCDIC-CP-CA, EBCDIC-CP-WT, EBCDIC-CP-NL
500 | EBCDIC-CP-BE, EBCDIC-CP-CH
813 | ISO-8859-7, ISO_8859-7
819 | ISO-8859-1, ISO_8859-1
920 | ISO-8859-9, ISO_8859-9
1200 | UTF-16
Parent topic: XML document coded character sets


Exceptions

For most exceptions, the XML text contains the part of the document that was parsed up to and including the point where the exception was detected. For encoding conflict exceptions, which are signaled before parsing begins, the length of the XML text is either zero or the XML text contains just the encoding declaration value from the document.

The kinds of exceptions are:

  • Continuable exceptions - Allow you to continue parsing optionally. Continuable exceptions have exception codes in the range 1 through 99, 100,001 through 165,535, or 200,001 to 265,535. The exception event in the example above has an exception number of 1 and thus is continuable.
  • Fatal exceptions - Do not allow continuation. Fatal exceptions have exception codes greater than 99 (but less than 100,000).

Returning from the exception event function with a non-zero return code normally causes the parser to stop processing the document, and return control to the program that invoked the PLISAXA or PLISAXB built-in.

For continuable exceptions, returning from the exception event function with a zero return code tells the parser to continue processing the document, although further exceptions may occur.

A special case applies to exceptions with exception numbers in the ranges 100,001 through 165,535 and 200,001 through 265,535. These ranges of exception codes indicate that the document's CCSID (determined by examining the beginning of the document, including any encoding declaration) is not identical to the CCSID value provided (explicitly or implicitly) by the calling built-in (PLISAXA or PLISAXB ), even if both CCSIDs are for the same basic encoding, EBCDIC or ASCII. For these exceptions, the exception code passed to the exception event contains the document's CCSID, plus 100,000 for EBCDIC CCSIDs, or 200,000 for ASCII CCSIDs. For instance, if the exception code contains 101,140, the document's CCSID is 01140. The CCSID value provided by the PLISAXA or PLISAXB built-in is either set explicitly as the last argument on the call or implicitly when the last argument is omitted and the value of the CODEPAGE compiler option is used.

Depending on the value of the return code after returning from the exception event function for these CCSID conflict exceptions, the parser takes one of these actions:

  • If the return code is zero, the parser proceeds using the CCSID provided by the PLISAX built-in being used.
  • If the return code contains the document's CCSID (that is, the original exception code value minus 100,000 or 200,000), the parser proceeds using the document's CCSID. This is the only case where the parser continues after a non-zero value is returned from one of the parsing events.
  • Otherwise, the parser stops processing the document, and returns control to the PLISAXA or PLISAXB built-in, which raises the ERROR condition.
Parent topic: XML Parser Support in PL/I


CBL_GET_PROGRAM_INFO (PL/I)

Returns information for a named program, or a program in the current call stack.

For COBOL, the CBL_GET_PROGRAM_INFO uses the save area defined for a COBOL program. The COBOL run-time system loads both .int and .gnt, providing access to the relevant save area for these types of programs.

A native object code program, however, may be in a state where it has been loaded by the COBOL run-time system, but not yet called. Until called, there is no save area and as such CBL_GET_PROGRAM_INFO could not be used on a native object code program (shared object, dynamic link library or executable).

To resolve this, you can embed a predefined structure into the program's resulting objects based on the compiler (COBOL or PL/I). That structure should contain a known symbol so the run time can easily locate the structure during execution. If the native object code program is loaded, but not yet executed, or if the object is a PL/I object, then this symbol can be located and program information can be extracted from the embedded structure.

The compiler creates the following structure for object code programs:

struct
{
    unsigned int version;
    unsigned int flags;
    union
    {
        void * p_savarea;
        Unsigned int PLI_attributes;
    }x;
} _mFinfo_<NAME>;

/* PLI_attributes bit values        */
#define PLI_AMODE24           0x00000001
#define PLI_AMODE31           0x00000002
#define PLI_EBCDIC            0x00000004
#define RESERVED1             0x000000F8
#define LANGUAGE              0x00000700
#define LANGUAGE_SPECIFIC     0x01FFF800
#define PLI_LENDIAN           0x00000800
#define PLI_FUTURE            0x01FFF000
#define RESERVED2             0xFE000000

Where:

<NAME> | The name of the main entry point or program
version | The version of the structure (initially set to 1)
flags | 0 = COBOL program 1 = PL/I program
p_savarea | The pointer to the COBOL program's savarea.
PLI_attributes | The returned PL/I attributes

The _mFinfo_<NAME> symbol must be made visible so the run time can locate it when necessary. In the COBOL run time, CBL_GET_PROGRAM_INFO works as normal except when the named program is found but no save area exists. When this happens, if the _mFinfo_<NAME> symbol is found, the associated structure is deciphered depending on version and flags. For COBOL, a pointer to the program's save area (p_savarea) allows you to access and return all relevant information for the given program. For PL/I, the relevant program information is extracted and returned from the PLI_attributes data item.

For PL/I, CBL_GET_PROGRAM_INFO return the program's attributes as it does for a COBOL program. The PL/I program returned bit meanings are:

Bit 0
0 | Program not compiled using the AMODE"24" Compiler directive.
1 | Program compiled using the AMODE"24" Compiler directive .
Bit 1
0 | Program not compiled using the AMODE"31" Compiler directive.
1 | Program compiled using the AMODE"31" Compiler directive .
Bit 2
0 | Program compiled using the CHARSET(ASCII) Compiler directive.
1 | Program compiled using the CHARSET(EBCDIC) Compiler directive.
Bit 3-5
Reserved for future use.
Bit 6
0 | Program not compiled using the DATA(24) Compiler directive.
1 | Program compiled using the DATA(24) Compiler directive.
Bit 7
0 | Program not compiled using the DATA-CONTEXT Compiler directive.
1 | Program compiled using the DATA-CONTEXT Compiler directive.
Bit 8-10
0 | Language is unknown.
1 | PL/I.
2 through 7 | Reserved.
Bit 11
Language-specific flag.
0 | PL/I-specific (little-endian).
1 | PL/I-specific (big-endian).
Bit 12-24
Language-specific flags.
Bit 25
0 | Program is not an application controller.
1 | Program is an application controller.
Bit 26
Reserved for future use.
Bit 27
0 | Program is not a .390 assembler program.
1 | Program is a .390 assembler program.
Bit 28-30
Reserved for future use.
Bit 31
Set for PL/I programs.
0 | COBOL.
1 | Non-COBOL.

The CBL_GET_PROGRAM_INFO routine modifies bits 8-10 to set the PL/I language and set bit 31 to indicate non-COBOL. The rest of the data item returns as is. Bits 3-7, and 25-30 are reserved to not conflict with existing programs that do not correctly check bit 31.

Getting program information on the current program and then iterating up the stack to retrieve caller program information is not supported for PL/I programs in the stack.

Parent topic: Language Concepts


Open PL/I SQL Options

  • DB2 SQL Support
  • HCO for SQL Server Compiler Directive Options for PL/I
    Using HCO for SQL compiler directive options with PL/I.
  • OpenESQL Support for Oracle PL/I Applications
    OpenESQL provides a run-time system that uses Oracle's native OCI API. You can use the OCI API to run Open PL/I applications.
  • OpenESQL Compiler Options for Open PL/I
Parent topic: Open PL/I User's Guide


DB2 SQL Support

Open PL/I enables you to develop PL/I applications that make use of databases maintained by IBM DB2 LUW. Open PL/I's DB2 SQL preprocessor allows you to compile and link PL/I applications containing embedded DB2 SQL statements to access these databases. This document gives the special instructions needed to code, compile, and link such Open PL/I applications.

Support for DB2 SQL is included in the standard Open PL/I product set, but you must obtain from Micro Focus a DB2 SQL license before it can be used. Also, before you can take advantage of EXEC SQL support, you must have installed and started IBM's DB2 product on your system.

You can code DB2 EXEC SQL statements in Open PL/I applications using the language defined in the IBM document DATABASE 2 Client/Server SOL Reference. Specific requirements for your SQL code are described in the sections that follow.

  • PL/I DB2 Stored Procedures
  • HCO for DB2 LUW Preprocessor
    Describes the HCO for DB2 LUW preprocessor.
  • DB2 SQL Preprocessor Options (Deprecated)
  • Coding DB2 SQL Statements in Open PL/I Applications
  • Sample Programs
  • Equivalent HCO for DB2 LUW Preprocessor Options
Parent topic: Open PL/I SQL Options


PL/I DB2 Stored Procedures

DB2 LUW allows embedded SQL calls to be executed as stored procedures. Stored procedures are routines executed directly by a DB2 LUW Server instance, rather than indirectly via a call to a routine from within a client application. The benefits of using DB2 stored procedures over SQL calls include enhanced modularity, security, and performance.

Stored procedures are stored at a local or remote DB2 LUW Server. Local DB2 LUW Server applications or remote DRDA applications can use the SQL statement CALL to invoke a stored procedure.

Note:
  • If you are running your stored procedure on DB2 for OS/390, through the DB2 Connect product, see your IBM DB2 documentation for other steps necessary to run the stored procedure.
  • For complete information on writing stored procedures and setting options for DB2 Database for Linux, UNIX, and Windows (LUW), see IBM's documentation on Developing User-defined Routines (SQL and External) and also their SQL reference material.
  • Working with Stored Procedures
  • Writing and Preparing Stored Procedures
  • Writing and Preparing Applications to Use Stored Procedures
  • Defining Stored Procedures under DB2 LUW
  • Compiling and linking stored procedures under DB2 LUW
  • Testing DB2 LUW Stored Procedures
  • Creating a CTF Trace for DB2 LUW Stored Procedures
  • Debugging PL/I DB2 LUW Stored Procedures
Parent topic: DB2 SQL Support


Working with Stored Procedures

To get a stored procedure up and running:

  1. To set up the initial environment:
    On Windows, do one of the following:
    1. Add your installation's executable (bin) directory to the PATH statement.
    2. Copy the following DLLs to the directory from which you execute the stored procedure. You need to do this for DB2 to be able to execute a PL/I stored procedure:
      • cblrtsm.dll
      • mffh.dll
      • mfhcolib.dll
      • mfsqlsmf.dll
      • cblctf.dll
      • dbghelp.dll
      • libxml2.dll
      • mfplimd.dll
      • mplicppm.dll
      • mpliemsg.lng
      • plidump.dll
      • xerces-c_2_8.dll

    In addition, see the IBM documentation for Building Micro Focus COBOL Routines on Windows.

  2. Code and prepare a stored procedure. See Writing and Preparing Stored Procedures for instructions.
  3. Code and prepare an application that calls the stored procedure. An SQL statement, CALL, in that application must use the same parameter list and linkage convention as the stored procedure that it invokes. See Writing and Preparing Applications to Use Stored Procedures for instructions.
  4. Define your stored procedure to the DB2 LUW Server by issuing a CREATE PROCEDURE command, which will place a row in the appropriate system table(s). See Defining Stored Procedures under DB2 LUW for additional details.
  5. Compile and link your stored procedure. See Compiling and Linking Stored Procedures under DB2 LUW for additional details.
  6. Debug and test your stored procedure. See Debugging Stored Procedures under DB2 LUW for additional details.
Parent topic: PL/I DB2 Stored Procedures
Related information
Compiling and linking stored procedures under DB2 LUW
Debugging PL/I DB2 LUW Stored Procedures
Defining Stored Procedures under DB2 LUW
Writing and Preparing Applications to Use Stored Procedures
Writing and Preparing Stored Procedures


Writing and Preparing Stored Procedures

A stored procedure is an application program that runs in the DB2 LUW Server's address space. It can contain most statements that an application program normally contains. It can consist of more than one program. Your stored procedure can call other programs as well as nested stored procedures but there are restrictions.

The application program that invokes the stored procedure can be in any language that supports SQL statements. You can write a stored procedure using many languages such as C, JAVA, COBOL or now SQL Procedure Language which is consistent with the Persistent Stored Module definition of the ANSI SQL99 standard.

The store procedure can be written in one language, for example JAVA, with the client written in another language, for example COBOL. When the languages differ, DB2 transparently passes the values between the client and the stored procedure so each program gets the values in the expected format defined by the CREATE PROCEDURE statement.

  • Preparing Stored Procedures
  • How an Application Works With a Stored Procedure
Parent topic: PL/I DB2 Stored Procedures


Preparing Stored Procedures

The following are high level tasks that must be completed before a stored procedure can be run on a DB2 LUW Server:

  1. Prepare the application according to your embedded SQL documentation for creating stored procedure.
  2. Define the stored procedure to the DB2 LUW Server. See Defining Stored Procedures under DB2 LUW.
  3. Place the stored procedure DLL on the DB2 LUW Server machine in a location specified in the CREATE PROCEDURE statement. If not specified, the default location is the function subdirectory under sqllib in the home directory of your DB2 LUW instance.
Note: IBM provides specific documentation on preparing stored procedures. Look in your IBM documentation for information on creating external routines and developing user-defined routines.
Parent topic: Writing and Preparing Stored Procedures


How an Application Works With a Stored Procedure

A typical stored procedure contains two or more SQL statements, and some manipulative or logical processing. In this example, your application, CALLSTPR, runs on a workstation client and calls a stored procedure, GETPRML. The following process occurs:

  1. The workstation application establishes a connection to the DB2 LUW Server.
  2. The SQL statement CALL tells the DB2 LUW Server that the application is going to run the stored procedure, GETPRML. The calling application provides the necessary parameters.
  3. The DB2 LUW Server searches the system tables for rows associated with stored procedure GETPRML.
  4. The DB2 LUW Server passes information about the request to the stored procedure.
  5. The stored procedure executes SQL statements.
  6. The stored procedure assigns values to the output parameters and then exits.
  7. Control returns to the calling application, which receives the output parameters.

The application can call more stored procedures or it can execute more SQL statements. The application designer determines whether to COMMIT work in the stored procedure that runs on the server, or in the client as a single transaction.

Parent topic: Writing and Preparing Stored Procedures


Writing and Preparing Applications to Use Stored Procedures

To invoke a stored procedure and to pass a list of parameters to the procedure, use the SQL statement CALL. Your application program can call several stored procedures.

After connecting to its server, an application can mix calls to stored procedures with SQL statements sent to the server.

  • Executing the SQL Statement CALL
  • Parameter Conventions
  • Using Indicator Variables to Speed Processing
  • Declaring Data Types for Passed Parameters
  • Limitations
Parent topic: PL/I DB2 Stored Procedures


Executing the SQL Statement CALL

Use the CALL statement to execute each series of SQL statements in your application.

Example 1

To call the stored procedure described in the topic How an Application Works with a Stored Procedure, your application might use this statement:

EXEC SQL
 CALL GETPRML(:V1, :V2);

If you use host variables in the CALL statement, you must declare them before using them.

Example 2

The example above is based on the assumption that none of the input parameters can have null values. To allow null values, code a statement like this:

EXEC SQL
 CALL GETPRML (:V1 :IV1, :V2 :IV2)

where :IV1 and :IV2 are indicator variables for the parameters.

Example 3

To use a host variable for the name of the stored procedure, code a statement like this:

EXEC SQL
 CALL :PROCNAME (:V1, :V2);

where :PROCNAME is the name of the stored procedure.

Parent topic: Writing and Preparing Applications to Use Stored Procedures


Parameter Conventions

See the IBM DB2 documentation for external routine parameter styles.

Note: Because DB2 LUW passes information to and from the stored procedure, specify NATIVE when passing any numeric parameters. For example:
PROC(EMPNO, SQLCD)

   DECLARE EMPNO CHAR(6),
           SQLCD FIXED BIN(31) NATIVE,
Parent topic: Writing and Preparing Applications to Use Stored Procedures


Using Indicator Variables to Speed Processing

If any of your output parameters require a lot of storage, do not pass the entire storage areas to your stored procedure, but declare an indicator variable for every large output parameter in your SQL statement CALL. Indicator variables are used in the calling program to pass only a two-byte area to the stored procedure and to receive the entire area from the stored procedure.

Note: If you are using the GENERAL WITH NULLS linkage convention, you must declare indicator variables for all of your parameters, so you do not need to declare another indicator variable for the large output parameters.

Assign a negative value to each indicator value associated with a large output variable. Then include the indicator variables in the CALL statement. This technique can be used whether the stored procedure linkage is GENERAL or GENERAL WITH NULLS.

For example, suppose that a stored procedure, STPROC2 defined with the GENERAL linkage convention takes one integer input parameter and one character output parameter of length 5000. It is wasteful to pass the 5000 byte storage area to the stored procedure. Instead, a PL/I program containing these statements passes only two bytes to the stored procedure for the output variable and receives all 5000 bytes from the stored procedure:

INNUM  FIXED BIN(31);
OUTCHAR CHAR(5000)
IND  FIXED BIN(15);
.
.
.
IND = -1;
EXEC SQL CALL STPROC2(:INNUM, :OUTCHAR :IND);
Parent topic: Writing and Preparing Applications to Use Stored Procedures


Declaring Data Types for Passed Parameters

A stored procedure must declare each parameter passed to it. In addition, the DATA TYPE declared in the declaration must be valid for the data source being used and must use a compatible host variable data type when calling the stored procedure. See SQL Data Types for more information.

For example:

CREATE PROCEDURE GETPRML
 (IN  PROCNM CHAR(18)
  ,IN SCHEMA CHAR (8)
  ,INOUT OUTCODE INTEGER
  ,INOUT PARMLIST CHAR (26)
  )
   LANGUAGE COBOL
   DETERMINISTIC
   READS SQL DATA
   NO DBINFO
   FENCED
   NOT THREADSAFE
   EXTERNAL NAME "GETPRML!GETPRML"
   PARAMETER STYLE GENERAL
   PROGRAM TYPE SUB
   RESULT SETS 0;
Note: Specify LANGUAGE COBOL since DB2 LUW does not directly support PL/I as an option. Also, the EXTERNAL name definition should match the case of the PL/I routine.

Define the stored procedure GETPRML as shown to match the definitions in the CREATE PROCEDURE statement:

GETPRML:
  PROC(PROCNM, SCHEMA, OUTCODE, PARMLST)
  external('GETPRML');

  DECLARE PROCNM CHAR(18),               /* INPUT parm -- PROCEDURE name */
          SCHEMA CHAR(8),                /* INPUT parm -- User's SCHEMA  */
          OUTCODE FIXED BIN(31) native, /* INOUT -- SQLCODE from        */
          PARMLST CHAR(26);              /* INOUT -- CURRENT TIMESTAMP   */

  EXEC SQL INCLUDE SQLCA;

  DECLARE TIMESTAMP CHAR(26);

  /************************************************************/
  /* Execute SELECT from SYSIBM.SYSDUMMY1 if TEST passed      */
  /************************************************************/

  if PROCNM = ‘TEST’ then
    do;
      exec sql
        SELECT CURRENT TIMESTAMP INTO :TIMESTAMP
          FROM SYSIBM.SYSDUMMY1;
    end;
  else
    do;
      TIMESTAMP = ‘PASS’;
      SQLCODE = -12;
    end;

  PARMLST = TIMESTAMP;
  OUT_CODE = SQLCODE;         /* return SQLCODE to caller */
  RETURN;
END GETPRML;
Parent topic: Writing and Preparing Applications to Use Stored Procedures
Related information
SQL Data Types


Limitations

IBM has not implemented the same support for all SQL syntax related to stored procedures in every supported language. For example, you cannot create COBOL stored procedures that use result sets or the EXEC SQL syntax that supports that functionality with the workstation version of DB2 LUW.

There is no support for structure, array, or vector parameters using the DB2 native precompiler. However, there is much more flexibility when using the OpenESQL preprocessor and an ODBC connection.

Additionally, Micro Focus stored procedures must be built as a dynamic link library (DLL) when running under Windows DB2 LUW servers. The following embedded SQL statements are not allowed in Micro Focus stored procedures on any platform:
  • CONNECT
  • DISCONNECT
  • SET CONNECTION
Parent topic: Writing and Preparing Applications to Use Stored Procedures


Defining Stored Procedures under DB2 LUW

A stored procedure is unusable until it is defined. Use the CREATE PROCEDURE command to do this. You can either use the DB2 command prompt or place the command in a program and compile and run it. If you use the DB2 command prompt, you first connect to the DB2 LUW Server where the stored procedure will be executed.

For example:

C:> db2 connect to sample

You can type in the command at the DB2 command prompt making sure you include continuation characters and command delimiters, or you can place the CREATE PROCEDURE in an ANSI text file. For example, if we placed the previous command in text file creproc.sql, the command that you would enter would be:

C:> db2 -td; -vf creproc.sql

where:

  • the -td option indicates the next character is the delimiter to end the command. In our example, it is a semicolon (;).
  • the -vf option indicates that the next token is the file to process that contains the SQL command script.

The create procedure statement must uniquely identify a stored procedure. If you want to change the stored procedure to either add or drop parameters or change functionality, you must use the DROP PROCEDURE command and then re-add it with the CREATE PROCEDURE command.

This example includes a CREATE PROCEDURE command identifying a unique stored procedure in a text file (which would be named creproc.sql).

DROP PROCEDURE GETPRML;
CREATE PROCEDURE GETPRML
  (IN PROCNM CHAR(18)
  ,IN SCHEMA CHAR(8)
  ,OUT OUTCODE INTEGER
  ,OUT PARMLST VARCHAR(30)
  )
    DYNAMIC RESULT SETS 0
    LANGUAGE COBOL
    PARAMETER STYLE GENERAL
    NO DBINFO
    FENCED
    NOT THREADSAFE
    READS SQL DATA
    PROGRAM TYPE SUB
    EXTERNAL NAME "GETPRML!GETPRML"  ;

When DB2 was originally developed, it did not support the CREATE PROCEDURE function, and it is possible to write COBOL stored procedures without doing a CREATE PROCEDURE. Examples of this method and the parmlist that is required are included in the DB2 LUW Application Development Client.

Parent topic: PL/I DB2 Stored Procedures


Compiling and linking stored procedures under DB2 LUW

Compiling and linking a PL/I stored procedure using DB2 LUW is a bit different than compiling and linking most PL/I applications. Use this procedure to compile and link DB2 stored procedures under DB2 LUW.

  1. Use mfplx to compile the program you want to use as a stored procedure with the DB2 SQL Option just like any DB2 LUW program. In this case though, you just want to create an OBJ file. To do this, specify the -c compiler option with mfplx.
    If your program contains stored procedure CALL statements, you must specify the CALL_RESOLUTION DB2 SQL option to prevent SQL error SQL0204 from occurring. For example:
    mfplx -sql db2 -optsql DB=SAMPLE getprml.pli -nolaxdcl –ppsql -c
    Note: Compile stored procedures using the -noaxdcl compiler option to prevent undeclared variables. Undeclared variables can cause a range of problems with stored procedures.

  2. Windows:

    To link the program as a Dynamic Link Library (.dll), you use CBLLINK rather than the normal PL/I link command.

    To link a PL/I DB2 stored procedure, you must link extra modules so that DB2 LUW can load the PL/I run time and load the PL/I routine properly.

    If the stored procedure is not defined with an OPTION of MAIN, add the systemsql.obj and setupdeffiles.obj object modules, as well as the mfplimd.lib and the 32-bit db2api.lib library files to the link command. For example:

    cbllink /d /V /K GETPRML.obj db2api.lib mfplimd.lib systemsql.obj setupdeffiles.obj

    If the stored procedure is not defined with an OPTION of MAIN, link these additional modules in the link command:

    • lpimainstub.obj
    • lpimain.obj
    • mfexttbl.lib

    For example:

    cbllink /d /V /K GETPRML.obj db2api.lib mfplimd.lib mfexttbl.lib systemsql.obj setupdeffiles.obj lpimainstub.obj lpimain.obj

  3. Copy the stored procedure object that is produced to the function directory under your DB2 instance.

    Note: By default, after calling a stored procedure, DB2 LUW does not unload it called until DB2 LUW is stopped. To avoid issues copying the .dll, you can do one of the following if you are not in a production environment.

    • Execute db2stop, copy the DLL, then execute db2start from a DB2 administrative command prompt.

    • Execute the following command from a DB2 command prompt:

    db2 update dbm cfg using KEEPFENCED NO

    Executing this command in a production environment has a significant performance impact, so it should not be used. Refer to your IBM documentation for more information on this command.

Parent topic: PL/I DB2 Stored Procedures


Testing DB2 LUW Stored Procedures

For testing DB2 LUW stored procedures in PL/I, you can use options other than coding a test client that require no coding.

  • If you have IBM's Data Studio product installed, you can use that to enter parameter information and execute the stored procedure.
  • Use a DB2 command prompt by first connecting to database and then calling the stored be entering CALL <stored procedure name> (parm1, parm2…..)

If the parameter is OUTPUT only, specify a question mark (?).

For example, to test the stored procedure defined earlier in this section, enter:

db2 connect to Sample
db2 call GETPRML ('TEST', 'TEST', 0, 'TEST')
Parent topic: PL/I DB2 Stored Procedures


Creating a CTF Trace for DB2 LUW Stored Procedures

Use this procedure to get a CTF trace for a PL/I DB2 stored procedure.

  1. Create a CTF configuration file with appropriate commands. For example:

    Windows:

    ## MFTRACE configuration file
mftrace.emitter.textfile#Format = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL) :$(DATA)
mftrace.dest=textfile
mftrace.emitter.binfile#location=c:\ctflogs
mftrace.emitter.textfile#location=c:\ctflogs
#  CTF Configuration Starting point for Open PLI Problem Determination
#  (Maximum amount of Open PL/I CTF tracing  )#
mftrace.emitter.es#level = 9999
# Maximum file size in "k" bytes
mftrace.emitter.textfile#MaxFilesize = 26000
# Maximum number of log files to keep.
mftrace.emitter.textfile#MaxGeneration = 6
################################################
# PL/I RTS Tracing
################################################
mftrace.level.mf.rts                    = info
mftrace.comp.mf.rts#api                 = true
mftrace.comp.mf.rts#syspgm              = true
mftrace.comp.mf.rts#pgm                 = true
mftrace.level.mf.rts.pli                = debug
mftrace.comp.mf.rts.pli#all             = true
mftrace.level.mf.pli.macropp            = info
mftrace.comp.mf.pli.macropp#compsrc     = true
    See the help topic "Configuration File for CTF" for more information on creating a CTF configuration file.
  2. Open a DB2 administrative command prompt and stop DB2 LUW by issuing one of these commands:
    db2stop
    or
    db2stop FORCE
  3. Enable CTF by setting the MFTRACE_CONFIG environment variable to the configuration file you just created. For example:

    Windows:

    SET MFTRACE_CONFIG=C:\CTFLOGS\CHKCTF.CFG
  4. Restart DB2 LUW by executing this command in a DB2 administrative command prompt:
    db2start
  5. Run program that calls the PL/I DB2 stored procedure.

    A CTF trace file generates, and the trace filename starts with the characters db2fmp.

Parent topic: PL/I DB2 Stored Procedures
Related information
Configuration File for CTF


Debugging PL/I DB2 LUW Stored Procedures

Restriction: This topic applies to Windows environments (local development) only.

It is possible to debug PL/I DB2 LUW Stored Procedures but care should be used when doing this. It is not recommended that production DB2 LUW servers be used because of the impact on processing and potential security issues. Using a VM image to debug the stored procedure is one option or using a single user version of the software like DB2 Express-C on a development workstation is another option.

Do the following before attempting to debug stored procedures:

  • When you install the DB2 LUW software, do not install the software using local system account as the ID to start all DB2 processes. Use the default setting of DB2ADMIN. Using local system account can cause the CodeWatch debugger to not attach the db2fmp process correctly.
  • The external name for the stored procedure definition needs to be in upper case so the definition would look something like this:
    CREATE PROCEDURE GETPRML
 (IN PROCNM CHAR(18)
 ,IN SCHEMA CHAR(8)
 ,INOUT OUTCODE INTEGER
 ,INOUT PARMLST CHAR(26)
 )
  LANGUAGE COBOL
  DETERMINISTIC
  READS SQL DATA
  NO DBINFO
  FENCED
  NOT THREADSAFE
  EXTERNAL NAME "GETPRML!GETPRML"
  PARAMETER STYLE GENERAL
  PROGRAM TYPE SUB
  RESULT SETS 0;
  • You should not use the EXTERNAL parameter in the PROC statement of the PL/I program. If you normally do, comment that code out like this:
    PROC(PROCNM, SCHEMA, OUTCODE, PARMLST); /* EXTERNAL('getprml'); */
  • Build and link the stored procedure for debugging. The commands would look like this:
    mfplx -sql db2 -optsql db=sample -deb -coffdebug -defext getprml.pli -c –ppsql
    SET LINK=-DEBUG
    cbllink /d /V /K getprml.obj db2api.lib mfplimd.lib systemsql.obj setupdeffiles.obj
  • Copy the DLL, STB, and PDB files to the \sqllib\function directory. STB files are created when setting the environment variable LINK=-DEBUG
  • Execute the stored procedure so that it gets loaded - for example using the DB2 command to call it.
  • Open an Enterprise Developer command prompt (32-bit) as ADMINISTRATOR
  • Set the CODEWATCH_SRCPATH and CODEWATCH_STBPATH environment variables to the \sqllib\function directory. For example:
    set CODEWATCH_SRCPATH=C:\Program Files\IBM\SQLLIB\FUNCTION
    set CODEWATCH_STBPATH=C:\Program Files\IBM\SQLLIB\FUNCTION
  • Find the PID for the DB2 LUW process that loaded the stored procedure. Look for db2fmp.exe.

    It is easier to find if you have 64-bit version of DB2 LUW installed since it is a 32-bit version.

    One tool that you could use is PSLIST which is available from www.sysinternals.com under PsTools download. The command to execute is:

    PSLIST DB2FMP

    The results would look something like this using 64-bit DB2 LUW:

    Name         Pid Pri Thd  Hnd   Priv       CPU Time    Elapsed Time
db2fmp64    2240   8   9  211  16660    0:00:00.655     0:00:50.512
db2fmp64    2240   8   9  211  16660    0:00:00.655     0:00:50.512
db2fmp64    2056   8   4  143  10888    0:00:00.046     0:00:15.241
db2fmp      2528   8   3  117  12172    0:00:00.140     0:00:15.163

    If more than one PID for db2fmp is listed, try them one at a time to determine which one is the stored procedure you want to debug. You could also use CTF trace to determine which PID is being used.

  • In the Enterprise Developer 32-bit command prompt, enter java -jar <installation path>/cw_java.jar -pid nnnn where nnnn is the PID number. For example, using the last PID displayed above, the command would be:
    java –jar <installation path>/cw_java.jar –pid 2528

    The CodeWatch window appears.

  • Select Shared Library from the Actions menu, enter the .dll name of the stored procedure you want to debug and click OK. For example:

  • Load the source symbols by typing the proc name of the stored procedure in the Env dropdown. For example:

  • Set a break point on the line where you want to stop the debugger. To do this, double click the line number. For example, double clicking line 15 will stop execution on line 15.

  • In the CodeWatch window, click Continue [image] to wait until the stored procedure is called again.
  • Call the stored procedure again in another process.
  • Switch back to the CodeWatch debugger window. If attached to the correct process, the debugger stops at the line set in the breakpoint.

    You can now perform debugging tasks including evaluating variables and stepping through code. When you return, the results of the stored procedure call are available to the calling process.

Parent topic: PL/I DB2 Stored Procedures


HCO for DB2 LUW Preprocessor

Micro Focus provides the same DB2 LUW preprocessor used by COBOL applications based on the HCO for DB2 LUW preprocessor. This preprocessor gives you access to all DB2 LUW preprocessor options, most options are not case sensitive, and it supports similar command line syntax used for creating ODBC, OCI or HCOSS application.

Note: Micro Focus also provides the original DB2 SQL preprocessor for backward compatibility which is now deprecated.
Parent topic: DB2 SQL Support
Related information
HCO for DB2 LUW Preprocessor Options


DB2 SQL Preprocessor Options (Deprecated)

The following DB2 SQL preprocessor options are supported by the Open PL/I driver program, mfplx:

-bind or -nobind
Determines whether or not a bind file is created. The bind file's name is specified by the -bindname option, if that option is used. Otherwise, the name defaults to the name of the input source file with the suffix .bnd.
-bindname b
Specifies the bind file name, b, if one is created.
-block t
Specifies the type of record blocking, t, to be used and how ambiguous cursors are to be treated. The valid types are:
unambig | Blocking occurs for read-only cursors, those that are not specified as FOR UPDATE OF, have no static DELETE WHERE CURRENT OF statements, and have no dynamic statements. Ambiguous cursors can be updated.
all | Blocking occurs for read-only cursors, those that are not specified as FOR UPDATE OF, and for which no static DELETE WHERE CURRENT OF statements are executed. Ambiguous and dynamic cursors are treated as read-only.
no | No blocking is done on any cursors in the package. Ambiguous cursors can be updated.
-datetime d
Determines the date and time format used when date and time fields are assigned to string representations in host variables. The possible formats are:
def | Use the date/time format associated with the country code of the database. This is also the default if -datetime is not specified.
usa IBM standard for United States form:

mm/ddlyyyy hh:mm xM (AM or PM).

eur IBM standard for European form:

dd.mm.yyyy hh.mm.ss.

iso International Standards Organization form:

yyyy–mm–dd hh.mm.ss.

jis Japanese Industrial Standards form:

yyyy–mm–dd hh:mm:ss.

loc | Local form, not necessarily equal to def.
-db2
Specifies that the DB2 version of SQL is to be used.
-dbname d
Specifies the original or alias name of a database. This option directs the preprocessor to process SQL statements against the specified database, d. If you omit this option, the preprocessor uses the default database. The default database is specified by the environment variable DB2DBDFT.
-E
Allows you to run the DB2 SQL preprocessor without running the Open PL/I compiler. The preprocessor output is saved using the file specified by the -ppdb2 option, if that option is used. Otherwise, the name defaults to the name of the input source file with the suffix .pp2. This option is useful for a faster syntax and semantic checking of your SQL statements.
-isolation I
Specifies the isolation level at which your program runs. The values of Iare:
cs | Cursor stability
rr | Repeatable read
ur | Uncommitted read
-optimize or -nooptimize
If you specify -optimize, SQLDA initialization is optimized for SQL statements that use host variables. Do not specify this option when using AUTOMATIC host variables or in other situations when the address of a host variable might change during execution of the program. -nooptimize is the default.
-plan or -noplan
Determines whether or not an access plan is created.
-ppdb2 [f]
Specifies the DB2 SQL preprocessor output file. This is useful when using the -E option.
-sqltwop
It is good programming practice to declare all SQL host variables before using them in SQL statements. However, if you are not able to do this, -sqltwop provides support for declarations of host variables subsequent to their use. This is done by making a preliminary pass over the source to detect all declarations, followed by a second pass to process the remaining SQL statements. In general, you should not need to use this option and incur the extra overhead it entails.
Parent topic: DB2 SQL Support


Coding DB2 SQL Statements in Open PL/I Applications

Specific requirements for your embedded SQL code are described in the sections that follow.

  • Defining the DB2 SQL Communications Area
  • Defining SQL Descriptor Areas
  • Embedding SQL Statements
  • Using Host Variables
  • Determining Equivalent SQL and PL/I Data Types
  • Determining Compatibility of SQL and PL/I Data Types
  • Using Host Structures
  • Using Indicator Variables
  • CONNECT TO Statement
  • COMPOUND Statement
  • Handling SQL Error Return Codes
Parent topic: DB2 SQL Support


Defining the DB2 SQL Communications Area

An Open PL/I program that contains SQL statements must include an SQL communications area (SQLCA). As shown in the example below, SQLCA includes an SQLCODE variable and an SQLSTATE variable.

The SQLCODE value is set by the Database Manager after each SQL statement is executed. An application can check the SQLCODE value to determine whether the last SQL statement was successful.

The SQLSTATE variable can be used as an alternative to the SQLCODE variable when analyzing the result of an SQL statement. Like the SQLCODE variable, the SQLSTATE variable is set by the Database Manager after each SQL statement is executed.

The SQLCA should be included by using the SQL INCLUDE statement:

exec sql include sqlca;

The SQLCA must not be defined within an SQL declare section. The scope of the SQLCODE and SQLSTATE declarations must include the scope of all SQL statements in the program.

/*--------------------------------------------------------------- */
/* DB2 SQL Communications Area                                    */
/* This should be included by the                                 */
/* 'EXEC SQL INCLUDE SQLCA;' statement.                           */
/* Do not place this within a SQL declare statement.              */
/*--------------------------------------------------------------- */
declare 1 sqlca,
  2 sqlcaid char(8),                 /* Eyecatcher = 'SQLA '      */
  2 sqlcabc fixed bin(31),           /* SQLCA size in bytes = 136 */
       2 sqlcode fixed bin(31),      /* SQL return code           */
       2 sqlerrm char(70) varying,   /* Error message tokens      */
       2 sqlerrp char (8),           /* Diagnostic information    */
       2 sqlerrd(1:6) fixed bin(31), /* Diagnostic information    */
       2 sqlwarn,                    /* Warning flags             */
         3 sqlwarn0 char(1),
         3 sqlwarnl char(1),
         3 sqlwarn2 char(1),
         3 sqlwarn3 char(1),
         3 sqlwarn5 char(1),
         3 sqlwarn6 char(1),
         3 sqlwarn7 char(1),
       2 sqltext,
         3 sqlwarn8 char(1),
         3 sqlwarn9 char(1),
         3 sqlwarna char(1),
         3 sqlstate char(5); /* State corresponding to SQLCODE */

/*    End of SQL Communications Area declaration */
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Defining SQL Descriptor Areas

The following statements require an SQLDA:

  • PREPARE statement-name INTO descriptor-name FROM host-variable
  • EXECUTE ... USING DESCRIPTOR descriptor-name
  • FETCH ... USING DESCRIPTOR descnptor-name
  • OPEN ... USING DESCRIPTOR descriptor-name
  • DESCRIBE statement-name INTO descriptor-name

Unlike the SQLCA, there can be more than one SQLDA in a program, and an SQLDA can have any valid name. An SQLDA should be included by using the SQL INCLUDE statement:

exec sql include sqlda;

The SQLDA must not be defined within an SQL declare section.

The Open PL/I SQLDA template includes %REPLACE statements for the SQL data types.

/*-------------------------------------------------------------------------------- */
/* DB2 SQL Descriptor Template                                                         */
/* This should be included by the 'EXEC SQL INCLUDE SQLDA;' statement.                 */
/* Do not place this within an SQL declare statement.                                  */
/*------------------------------------------------------------------------------------ */
declare 1 sqlda based(sqldaptr),                                                       */
   2 sqldaid        char(8),                     /* Eye catcher 'SQLDA   '             */
   2 sqldabc fixed bin(31),                      /* SQLDA size in bytes 16 + 44 * SQLN */
   2 sqln           fixed bin(15),               /* Number of SQLVAR elements          */
   2 sqld           fixed bin(15),               /* Number of used SQLVAR elements     */
   2 sqlvar(1:sqlsize refer(sqln)),              /* Variable descriptor                */
     3 sqltype      fixed bin(15),               /* Variable data type                 */
     3 sqllen       fixed bin(15),               /* Variable length                    */
     3 sqldata      pointer,                     /* Pointer to variable data value     */
     3 sqlind       pointer,                     /* Pointer to null indicator          */
     3 sqlname      char(30) var;                /* Variable name                      */
declare sqlsize fixed bin(15);                   /* Number of sqlvars (sqln)           */
declare sqldaptr pointer;
/* End of SQL Descriptor Template declaration */

/* replaces for SQL type codes                                                         */
/* replaces of the SQL_TYP_Nxxnnn means with Null indicator                            */
%replace SQL_TYP_DATE      by 384; /* DATE */
%replace SQL_TYP_NDATE     by 385;
%replace SQL_TYP_TIME      by 388; /* TIME */
%replace SQL_TYP_NTIME     by 389;
%replace SQL_TYP_STAMP     by 392; /* TIMESTAMP */
%replace SQL_TYP_NSTAMP    by 393;
%replace SQL_TYP_VARCHAR   by 448; /* VARCHAR(I) varying length string I<=4000*/41)
%replace SQL_TYP_NVARCHAR  by 449;
%replace SQL_TYP_CHAR      by 452; /* CHAR(I) - fixed length string */
%replace SQL_TYP_NCHAR     by 453;
%replace SQL_TYP_LONG      by 456; /* LONG VARCHAR - varying length I > 4000 */
%replace SQL_TYP_NLONG     by 457;
%replace SQL_TYP_CSTR      by 460; /* varying length string for C */
%replace SQL_TYPNCSTR      by 461;
%replace SQL_TYP_VARGRAPH  by 464; /* VARGRAPHIC(I) - varying length */
%replace SQL_TYP_NVARGRAPH by 465;
%replace SQL_TYP_GRAPHIC   by 468; /* GRAPHIC(I) - fixed length graphic */
%replace SQL_TYP_NGRAPHIC  by 469;
%replace SQL_TYP_LONGRAPH  by 472; /* LONG VARGRAPHIC(I) - varying length */

%replace SQL_TYP_NLONGRAPH by 473;
%replace SQL_TYP_LSTR      by 476; /* varying length string for Pascal */
%replace SQL_TYP_NLSTR     by 477;
%replace SQL_TYP_FLOAT     by 480; /* FLOAT - 8-byte floating point */
%replace SQL_TYP_NFLOAT    by 481;
%replace SQL_TYP_DECIMAL   by 484; /* DECIMAL (p,q), sqllen q + (256 * p) */
%replace SQL_TYP NDECIMAL  by 485;
%replace SQL_TYP_ZONED     by 488; /* Zoned Decimal -> DECIMAL (m,n) */
%replace SQL_TYP_NZONED    by 489;
%replace SQL_TYP_INTEGER   by 496; /* INTEGER - 4-byte signed integer */
%replace SQL_TYP_NINTEGER  by 497;
%replace SQL_TYP_SMALL     by 500; /* SMALLINT - 2-byte signed integer*/
%replace SQL_TYP NSMALL    by 501;
%replace SQL_TYP_NUMERIC   by 504; /* NUMERIC -> DECIMAL (m,n) */
%replace SQL_TYP_NNUMERIC  by 505;

/* End of EXEC SQL INCLUDE SQLDA  -------------------------------------------------*/
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Embedding SQL Statements

You can add SQL statements to your program wherever executable statements can appear. Each SQL statement must begin with EXEC (or EXECUTE) SQL and end with a semicolon (;).

For example, an UPDATE statement might be coded as follows:

exec sql update Department
   set Mgrno    = :Mgr_Num
   where Deptno = :Int_Dept;

Comments

PL/I comments can be included in embedded SQL statements wherever a blank is allowed.

Continuation

The line continuation rules for embedded SQL statements are the same as for other PL/I statements.

Including Code

SQL statements or PL/I host variable declaration statements can be included by placing the following SQL statement at the point in the source code where the statements are to be embedded:

exec sql include {filename | 'filename'};

filename can be enclosed in single quote characters ('). Quotes are required if filename contains any non-alphanumeric characters, as for example,

'inventory.db001'.

Names

Any valid PL/I variable name can be used for a host variable, subject to the following restriction: Do not use host variable names or external entry names that begin with "SQL". These names are reserved for the database manager or Open PL/I. The length of a host variable name must not exceed 30 characters.

Statement Labels

With the exception of the END DECLARE SECTION statement and the INCLUDE text-filename statement, executable SQL statements, like PL/I statements, can have a label prefix.

WHENEVER Statement

The target for a GOTO clause in an SQL WHENEVER statement must be a label in the PL/I source code and must be within the scope of any SQL statements affected by the WHENEVER statement.

Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Using Host Variables

All host variables used in SQL statements must be explicitly declared. A host variable used in an SQL statement must be declared prior to the first use of the host variable in an SQL statement, except when the -sqltwop precompiler option is used. In addition:

  • All host variables within an SQL statement must be preceded by a colon (:).
  • The names of host variables must be unique within a program, even if the host variables are in different blocks or procedures.
  • An SQL statement that uses a host variable must be within the scope of the statement in which the variable is declared.
  • A host variable cannot be declared as an array.
  • Declaring Host Variables
  • Numeric Host Variables
  • Character Host Variables
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Declaring Host Variables

Host variable declarations can be made at the same places as ordinary PL/I variable declarations.

Not all PL/I data types are acceptable for host variables. The precompiler does not use the data attribute defaults specified in the PL/I DEFAULT statement. If the declaration for a variable is not recognized, any statement that references the variable may result in the message "The host variable token ID is not valid".

The SQL precompiler uses only the names and data attributes of host variable declarations; the alignment, scope, and storage class attributes are ignored.

Parent topic: Using Host Variables


Numeric Host Variables

The syntax for numeric host variable declarations is as follows:

DECLARE var-name-spec {BINARY | DECIMAL} scale-spec align-scope-storage ;

where:

var-name-spec | is {variable-name | (variable-name, ...) }
scale-spec | is {FIXED [(precision [,scale])] | FLOAT [(precision)]}
align-scope-storage | is any set of PL/I alignment, scope, or storage class attributes
Note:
  • BINARY | DECIMAL and FIXED | FLOAT can be specified in either order.
  • The precision and scale attributes can follow BINARY | DECIMAL instead of FIXED | FLOAT.
  • A value for scale can be specified only for DECIMAL FIXED.
  • DCL, BIN, and DEC are accepted as abbreviations for DECLARE, BINARY, and DECIMAL, respectively.

Parent topic: Using Host Variables


Character Host Variables

The syntax for character host variable declarations is as follows:

DECLARE var-name-spec CHARACTER [(length)] [VARYING] align-scope-storage ;

where:

var-name-spec | is {variable-name | (variable-name, ...) }
align-scope-storage | is any set of PL/I alignment, scope, or storage class attributes

Note:
  • For non-varying character host variables, length must be a constant no greater than the maximum length for SQL CHAR data.
  • For varying-length character host variables, length must be a constant greater than the maximum length for SQL LONG VARCHAR data.
  • DCL, CHAR, and VAR are accepted as abbreviations for DECLARE, CHARACTER, and VARYING, respectively.
Parent topic: Using Host Variables


Determining Equivalent SQL and PL/I Data Types

The base SQLTYPE and SQLLEN of host variables are determined according to the following table. If a host variable appears with an indicator variable, the SQLTYPE is the base SQLTYPE plus one.

PL/I Data Type | SQLTYPE of Host Variable | SQLLEN of Host Variable | SQL Data Type
BIN FIXED(n), n < 16 | 500 | 2 | SMALLINT
BIN FIXED(n), 16 ? n ? 31 | 496 | 4 | INTEGER
DEC FIXED(p,s) | 484 | p (byte 1) s (byte 2) | DECIMAL(p,s)
BIN FLOAT(p), 24 ? n ? 52 | 480 | 8 | FLOAT
CHAR(n), 1 ? n ? 254 | 452 | n | CHAR(n)
CHAR(n) VARYING, 1 ? n ? 4000 | 448 | n | VARCHAR(n)
CHAR(n) VARYING, n > 4000 | 456 | n | LONG VARCHAR
  • For FLOAT data, only double-word BIN FLOAT is supported.
  • Precisions, where appropriate, must be specified with integer constants. Default values are not provided.
  • The SQLDA include file has %REPLACE statements for the SQL data types.

The following table can be used to determine the PL/I data type that is equivalent to a given SQL data type.

SQL Data Type | PL/I Equivalent | Notes
SMALLINT | BIN FIXED(15) |
INTEGER | BIN FIXED(31) |
DECIMAL(p,s) | DEC FIXED(p) or DEC FIXED(p,s) | 1 ? p ? 31 and 0 ? s ? p
FLOAT | BIN FLOAT(p) | 24 ? p ? 52
CHAR(n) | CHAR(n) | 1 ? n ? 254
VARCHAR(n) | CHAR(n) VAR | 1 ? n ? 4000
LONG VARCHAR | CHAR(n) VAR | 4000 < n
DATE | CHAR(n) | 10 ? n
TIME | CHAR(n) | 8 ? n
TIMESTAMP | CHAR(n) | 26 ? n
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Determining Compatibility of SQL and PL/I Data Types

PL/I host variables in SQL statements must be type compatible with the columns that use them:

  • Numeric data types are compatible with each other. A SMALLINT, INTEGER, DECIMAL, or FLOAT column is compatible with a PL/I host variable of BIN FIXED(15), BIN FIXED(31), DECIMAL(p,s), or BIN FLOAT(n), where 24 ? n ? 53.
  • Character data types are compatible with each other. A CHAR or VARCHAR column is compatible with a fixed-length or varying-length PL/I character host variable. When necessary, the Database Manager automatically converts a fixed-length character string to a varying-length string or a varying-length string to a fixed-length string.
  • Datetime data types are compatible with character host variables. A DATE, TIME, or TIMESTAMP column is compatible with a fixed-length or varying-length PL/I character host variable.
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Using Host Structures

A PL/I host structure name can be a structure name. For example:

dcl 1 A,
      2  B,
        3  C1 char(...),
        3  C2 char(...);

In this example, B is the name of a host structure consisting of the scalar members C1 and C2.

However, structures (whether level 1 structures or substructures) may not be referenced in SQL statements. Only scalar members may be so referenced.

A fully qualified member name must be no more than 30 characters in length.

Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Using Indicator Variables

An indicator variable is a two-byte integer (BIN FIXED(15)). On retrieval, an indicator variable is used to show whether its associated host variable has been assigned a null value. On assignment to a column, a negative indicator value is used to indicate that a null value should be assigned.

Indicator variables are declared in the same way as host variables and the declarations of the two can be mixed in any way that seems appropriate.

Given the statement:

exec sql fetch Cls_Cursor into  :Cls_Cd,
                                :Day  :Day_Ind,
                                :Bgn  :Bgn_Ind,
                                :End  :End_Ind;

the variables could be declared as follows:

exec sql begin declare section;
dcl Cls_Cd     char(7);
dcl Day        bin fixed(15);
dcl Bgn        char(8);
dcl End        char(8);
dcl (Day_Ind, Bgn_Ind, End_Ind) bin fixed(15);
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


CONNECT TO Statement

You can use a host variable to represent the database name you want your application to connect to. For example:

exec sql connect to :dbase;

If a host variable is specified:

  • It must be a character or character varying variable.
  • It must be preceded by a colon and must not be followed by an indicator variable.
  • The server-name that is contained within the host variable must be left-justified.
  • If the length of the server-name is less than the length of the fixed-length character host variable, it must be padded on the right with blanks.
    dcl dbase char(10);
dbase = 'SAMPLE';    /*four blanks are */
                     /* automatically appended */
exec sql connect to :dbase;
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


COMPOUND Statement

Open PL/I requires a trailing semicolon after the start of an SQL compound statement. For example:

exec sql begin compound atomic static;
      select count(*) into :tmp3 from department;
      select count(*) into :tmp4 from project;
end compound;
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Handling SQL Error Return Codes

Your DB2 product includes a routine that translates SQLCODE error values into readable text messages. When you process your program source with Open PL/I's DB2 SQL precompiler, an %INCLUDE statement is inserted into your program, and the include file this incorporates into your program contains a declaration of this SQLCODE translator routine as an entry, as follows:

declare sqldb2err entry(fixed bin(15) value,
                                    /* Buffer Size   */
               fixed bin(15) value, /* Line Width    */
               any,                 /* SQLCA         */
               any)                 /* Buffer        */
      returns(fixed bin(15))
      external('sqlgintp');

The return code values are:

  • >0 Length of message
  • -1 Internal DB2 error
  • -2 No error, SQLCODE = 0
  • -3 Invalid SQLCODE, no such error
  • -4 Line width is 0
  • -5 Invalid SQLCA, bad buffer address or bad buffer size

Example:

declare errmsg character(200);

exec sql connect to MYDB;
if sqlca.sqlcode < 0 then do;
   put skip list('Connect failed');
   /* Now print out reason for failure for most */
   /* recent SQL statement (i.e., the connect) */
   msg_len = sqldb2err(size(errmsg),0,sqlca,errmsg);
   put skip list(substr(errmsg,1,msg_len));
   return;
   end;

You do not need to declare sqldb2err. This is done for you automatically, as described above.

For more information about this routine, see SQLGINTP (Get Error Message) in your IBM platform-specific DATABASE 2 Programming Reference manual.

Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Sample Programs

  • Open PL/I DB2 SQL Sample 1 Program
  • Compilation, Linking, and Execution
  • Open PL/I DB2 SQL Sample 2 Program
Parent topic: DB2 SQL Support


Open PL/I DB2 SQL Sample 1 Program

filename: sample1.sqp

sample1: proc options(main);

/*                                                  */
/* This program shows the usage of host-variables,  */
/* indicators, and some common SQL statements       */

/* The database this program uses is the IBMSAMPL   */
/* database that your DB2 product uses. You must be */
/* able to run the IBM DB2 demo sample program in   */
/* order to be able to run this program.            */
/*                                                  */

dcl idx fixed bin(15);
dcl errmsg character(200);
dcl msg_len fixed bin(15);

exec sql include sqlca;

exec sql begin declare section;
   dcl cnt fixed bin(15);
   dcl projno char(6);
   dcl projname char(24) varying;
   dcl deptno char(6);
   dcl respemp char(6);

   dcl prstaff float bin(24);
   dcl prstaff_ind fixed bin(15);

   dcl prstdate char(10);
   dcl prstdate_ind fixed bin(15);

   dcl prendate char(10);
   dcl prendate_ind fixed bin(15);

   dcl majproj char(6);
   dcl majproj_ind fixed bin(15);
exec sql end declare section;

/* Set up error label for all SQL statements. */
exec sql whenever sqlerror goto err_label;

/* Connect to the IBM DB2 sample demo data base */
exec sql connect to IBMSAMPL;

/* Determine how many rows are in table project. */
exec SQL SELECT COUNT(*) INTO :cnt from project;

put skip edit('Number of rows in table project:', cnt) (a(40),x,f(3,0));
put skip list('All the rows for project are:');
put skip;

/* Declare and use a cursor to fetch each row. */
exec sql declare cl cursor for
  select projno, projname, deptno, respemp, prstaff,
         prstdate, prendate, majproj
  from project;

exec sql open cl;
do idx = 1 to cnt;
   prstaff = 0;       /* re-init */
   prstdate = ' ';    /* re-init */
   prendate = ' ';    /* re-init */
   majproj = ' ';     /* re-init */
   exec sql fetch cl into :projno,
                          :projname,
                          :deptno,
                          :respemp,
                          :prstaff  :prstaff_ind,
                          :prstdate :prstdate_ind,
                          :prendate :prendate_ind,
                          :majproj  :majproj_ind;
   put edit (projno, projname, deptno, respemp, prstaff, prstdate,
             prendate, majproj)
            (a(6),x,a(24),x,a(3),x,a(6),x,f(5,2),x,a(10),x,a(10),x,a(6));
   put skip;
   end;

 return;

err_label:
   msg_len = sqldb2err(200,0,sqlca,errmsg);
   put skip list(substr(errmsg,1,msg_len));

end sample1;
Parent topic: Sample Programs


Compilation, Linking, and Execution

mfplx –sql db2 –optsql db=sample sample1.sqp

sample1.sqp
Number of rows in table project:         20
All the rows for project are:
AD3100 ADMIN SERVICES        DO1 000010  6.50 01/01/1982 02/01/1983
AD3110 GENERAL ADMIN SYSTEMS D21 000070  6.00 01/01/1982 02/01/1983 AD3100
AD3111 PAYROLL PROGRAMMING   D21 000230  2.00 01/01/1982 02/01/1983 AD3110
AD3112 PERSONNEL PROGRAMMING D21 000250  1.00 01/01/1982 02/01/1983 AD3110
AD3113 ACCOUNT PROGRAMMING   D21 000270  2.00 01/01/1982 02/01/1983 AD3110
IF1000 QUERY SERVICES        CO1 000030  2.00 01/01/1982 02/01/1983
IF2000 USER EDUCATION        CO1 000030  1.00 01/01/1982 02/01/1983
MA2100 WELD LINE AUTOMATION  DO1 000010 12.00 01/01/1982 02/01/1983
MA2110 W L PROGRAMMING       Dl1 000060  9.00 01/01/1982 02/01/1983 MA2100
MA2111 W L PROGRAM DESIGN    Dl1 000220  2.00 01/01/1982 12/01/1982 MA2110
MA2112 W L ROBOT DESIGN      Dl1 000150  3.00 01/01/1982 12/01/1982 MA2110
MA2113 W L PROD CONT PROGS   D11 000160  3.00 02/15/1982 12/01/1982 MA2110
OP1000 OPERATION SUPPORT     E01 000050  6.00 01/01/1982 02/01/1983
0P1010 OPERATION             E11 000090  5.00 01/01/1982 02/01/1983 OP1000
0P2000 GEN SYSTEMS SERVICES  E01 000050  5.00 01/01/1982 02/01/1983
OP2010 SYSTEMS SUPPORT       E21 000100  4.00 01/01/1982 02/01/1983 OP2000
OP2011 SCP SYSTEMS SUPPORT   E21 000320  1.00 01/01/1982 02/01/1983 0P2010
OP2012 APPLICATIONS SUPPORT  E21 000330  1.00 01/01/1982 02/01/1983 0P2010
092013 DB/DC SUPPORT         E21 000340  1.00 01/01/1982 02/01/1983 0P2010
PL2100 WELD LINE PLANNING    B01 000020  1.00 01/01/1982 09/15/1982 MA2100
Parent topic: Sample Programs


Open PL/I DB2 SQL Sample 2 Program

filename: sample2.sqp

sample2: proc options(main);

   /* Sample program 2                                              */
   /* Example of using a user defined SQLDA                         */

   /* The database this program uses is the IBMSAMPL database that  */
   /* your DB2 product uses. You must be able to run the IBM DB2    */
   /* demo sample program in order to be able to run this program   */

   /* Uses a table of the form:                                     */
   /*    create table project                                       */
   /*       (projno char(6) not null,                               */
   /*       projname varchar(24) not null,                          */
   /*       deptno char(3) not null,                                */
   /*       respemp char(6) not null,                               */
   /*       prstaff dec(5,2),                                       */
   /*       prstdate date)                                          */

dcl k fixed bin(15);

exec sql include sqlca;
exec sql include sqlda;

exec sql begin declare section;
   dcl cnt fixed bin(15);
exec sql end declare section;

sqlsize 6;                     /* Lets only look at the 1st 6 columns */
allocate sqlda set(sqldapntr); /* sets sqln */
sqldaptr->sqld = 6;

dcl projno char(6) based;
sqldaptr->sqlda.sqlvar(1).sqltype = SQL_TYP_CHAR;
allocate projno set(sqldaptr->sqlda.sqlvar(1).sqldata);
sqldaptr->sqlda.sqlvar(1).sqllen = 6;

dcl projname char(24) var based;
saldaptr->sqlda.sqlvar(2).sqltype = SQL_TYP VARCHAR;
allocate projname set(sqldaptr->sqlda.sqlvar(2).sqldata);
sqldaptr->sqlda.sqlvar(2).sqllen = 24;

dcl deptno char(3) based;
sqldaptr->sqlda.sqlvar(3).sqltype = SQL_TYP_CHAR;
allocate deptno set(sqldaptr->sqlda.sqlvar(3).sqldata);
sqldaptr->sqlda.sqlvar(3).sqllen = 3;

dcl respemp char(6) based;
sqldaptr->sqlda.sqlvar(4).sqltype = SQL_TYP_CHAR;
allocate respemp set(sqldaptr->sqlda.sqlvar(4).sqldata);
sqldaptr->sqlda.sqlvar(4).sqllen = 6;

dcl prstaff float(24) binary based;
sqldaptr->sqlda.sqlvar(5).sqltype = SQL_TYP_FLOAT;
allocate prstaff set(sqldaptr->sqlda.salvar(5).sqldata);
sqldaptr->sqlda.sqlvar(5).sqllen = 8;

dcl prstdate char(10) based;
sqldaptr->sqlda.sqlvar(6).sqltype = SQL_TYP_CHAR;
allocate prstdate set(sqldaptr->sqlda.sqlvar(6).sqldata);
sqldaptr->sqlda.sqlvar(6).sqllen = 10;

exec sql connect to IBMSAMPL;
if SQLCA.SQLCODE < 0 THEN do;
   put skip list('Connect failed');
   return;
   end;
  else put skip list('Connect OK');
  put skip;
  exec sql whenever sqlerror goto err_label;
  put skip list('Projno Projname                 Dpt Respemp Prst Prstdate');
  put skip;

  exec sql declare cl cursor for select * from project;
  exec sql open cl;
  exec sql whenever not found go to done;
  do while ('1'b1);  /* do till fetch raises not found error */
     exec sql fetch c1 using descriptor :sqldaptr;
     put edit (sqldaptr->sqlda.sqlvar(1).sqldata->projno,
               sqldaptr->sqlda.sqlvar(2).sqldata->projname,
               sqldaptr->sqlda.sqlvar(3).sqldata->deptno,
               sqldaptr->sqlda.sqlvar(4).sqldata->respemp,
               sqldaptr->sqlda.sqlvar(5).sqldata->prstaff,
               sqldaptr->sqlda.sqlvar(6).sqldata->prstdate)
              (a(6),x,a(24),x,a(3),x,a(6),x,f(5,2),x,a(10));
     put skip;
     end;
done:
   exec sql whenever not found continue;   /* turn off */

   put skip;
   return;
err_label:
   put skip list('Branched to err_label');
   put skip list('sqlcode =', sqlcode);
   put skip list('sqlerrm =' , sqlerrm);
   put skip list('sqlstate =', sqlstate);
   return;

end sample2;

Output

Connect OK

Projno Projname              Opt Respemp  Prst Prstdate
AD3100 ADMIN SERVICES        D01 000010   6.50 01/01/1982
AD3110 GENERAL ADMIN SYSTEMS D21 000070   6.00 01/01/1982
AD3111 PAYROLL PROGRAMMING   D21 000230   2.00 01/01/1982
AD3112 PERSONNEL PROGRAMMING D21 000250   1.00 01/01/1982
AD3113 ACCOUNT PROGRAMMING   D21 000270   2.00 01/01/1982
1F1000 QUERY SERVICES        CO1 000030   2.00 01/01/1982
1F2000 USER EDUCATION        CO1 000030   1.00 01/01/1982
MA2100 WELD LINE AUTOMATION  DO1 000010  12.00 01/01/1982
MA2110 W L PROGRAMMING       D11 000060   9.00 01/01/1982
MA2111 W L PROGRAM DESIGN    D11 000220   2.00 01/01/1982
MA2112 W L ROBOT DESIGN      D11 000150   3.00 01/01/1982
MA2113 W L PROD CONT PROGS   D11 000160   3.00 02/15/1982
OP1000 OPERATION SUPPORT     E01 000050   6.00 01/01/1982
OP1010 OPERATION             E11 000090   5.00 01/01/1982
OP2000 GEN SYSTEMS SERVICES  E01 000050   5.00 01/01/1982
OP2010 SYSTEMS SUPPORT       E21 000100   4.00 01/01/1982
OP2011 SCP SYSTEMS SUPPORT   E21 000320   1.00 01/01/1982
0P2012 APPLICATIONS SUPPORT  E21 000330   1.00 01/01/1982
0P2013 DB/DC SUPPORT         E21 000340   1.00 01/01/1982
PL2100 WELD LINE PLANNING    B01 000020   1.00 01/01/1982
Parent topic: Sample Programs


Equivalent HCO for DB2 LUW Preprocessor Options

This table shows equivalent HCO for DB2 LUW preprocessor -optsql DB2 preprocessor options to the DB2 SQL preprocessor options.

HCO for DB2 LUW Preprocessor Option | DB2 Preprocessor Option
bind | -bind
bind=file_name | -bindname file_name
block=block_option | -block block_option
format=date/time_format | -datetime date/time_format
db=name | -dbname name
nobind | -nobind
isolation=option | -isolation option
access=package_name | -package package_name

To create a package TEST1 using a database named sample and a BIND file test1.bnd would be:

-optsql "db=sample access=test1 bind=test1"
Parent topic: DB2 SQL Support


HCO for SQL Server Compiler Directive Options for PL/I

Restriction: This topic applies to Windows environments (local development) only.

Syntax

To set an HCO for SQL Server compiler directive option for the PL/I compiler, use the following syntax:
mfplx pliProgName –sql odbc –optsql "SQLPrecompilerOption [...]"

Recommended Options

We recommend that you set the following HCO for SQL Server compiler directive options for PL/I when emulating mainframe settings using SQL:

  • BEHAVIOR=OPTIMIZED
  • CHECKDUPCURSOR
  • CHECKSINGLETON
  • DATE=USA
  • DBMAN=ODBC
  • DETECTDATE
  • DIALECT=MAINFRAME
  • MARS
  • NOCHECK
  • TARGETDB=MSSQLSERVER
  • TIME=USA
Note: Some of these options are specific to HCO for SQL Server, and some are available to both HCO for SQL Server and standard SQL.

Examples

Compiling
Compile a batch program to qualify tables using the QUALIFIER directive:
mfplx TESTPGM.PLI –sql odbc –optsql "QUALIFIER=HCOSQL" -isuffix cblrtssi –nologo
Compiling, Linking, and Binding
Compile 3 subroutines with a main program that calls routines to object files so it can be linked and then bound:
mfplx defplan0.pli -sql odbc -optsql "DBRMLIB" -isuffix -f w –c
mfplx defplan1.pli -sql odbc -optsql "DBRMLIB" -isuffix -f w –c
mfplx defplan2.pli -sql odbc -optsql "DBRMLIB" -isuffix -f w –c
mfplx defplan3.pli -sql odbc -optsql "DBRMLIB" -isuffix -f w -c
Link object files:
ldpli defplan0.obj defplan1.obj defplan2.obj defplan3.obj cblrtssi -out:defplan0.exe
Bind:
dsn system(hcodemo) @defplan0.hcodsn
Parent topic: Open PL/I SQL Options
Related reference
SQL Compiler Directive Options - HCOSS


OpenESQL Support for Oracle PL/I Applications

OpenESQL provides a run-time system that uses Oracle's native OCI API. You can use the OCI API to run Open PL/I applications.

The benefits of this run-time system are:

  • Better performance and reliability compared to Oracle's ODBC drivers
  • Support for BLOB, CLOB, BLOB_LOCATOR and CLOB_LOCATOR host variables
  • A date and timestamp formatting option that conforms to Oracle session settings for NLS_DATE_FORMAT, NLS_TIMESTAMP_FORMAT and NLS_TIMESTAMP_TZ_FORMAT
  • More comprehensive compile time checking with the SQL CHECK directive
  • Switch module support for Oracle OCI, as well as for JES-initiated transactions connecting to Oracle data sources using OCI.
  • Compiling a PL/I application for OCI
    Gives instruction on use of directives when compiling a PL/I application for OCI
  • Setting BLOB and CLOB variables
    Describes and illustrates how to declare BLOB and CLOB variables for compiling PL/I programs for Oracle OCI.
  • Date and Timestamp Formatting with OpenESQL for OCI
    Shows the Oracle OpenESQL date and timestamp statements executed in PL/I when opening an OCI connection.
  • Additional Considerations for Oracle
    Applications migrating from OpenESQL for ODBC, or from other database systems, should note the following.
  • Recommended OpenESQL Directives for Open PL/I
    Describes the SQL directives to use with Open PL/I for compatibility with OODBC, when migrating DB2 applications, and for Oracle date/time formatting.
  • Supported OpenESQL Compiler Options
    Lists supported OpenESQL compiler options for SQL ODBC and SQL OCI.
  • Switch Module Support
    Describes switch modules ESOCIXA.CBL and ESOCIOPC.CBL, used to connect to Oracle using OCI.
  • Using the OpenESQL OCI Directive with PL/I: Examples
    Provides examples of how to compile and link PL/I programs for OpenESQL OCI.
Parent topic: Open PL/I SQL Options


Compiling a PL/I application for OCI

To compile an Open PL/I application for OCI, use the PL/I directive -SQL OCI rather than -SQL ODBC. To use SQL CHECK directive when compiling for OCI, the SQL DB directive setting must match the appropriate entry in the tnsnames.ora configuration file. For example:

-OPTSQL "DB=XE CHECK"
Parent topic: OpenESQL Support for Oracle PL/I Applications


Setting BLOB and CLOB variables

For compiling a PL/I application for OCI, declare BLOB and CLOB variables as shown:

    DCL TEST_BLOB SQL TYPE IS BLOB(4K);
    DCL TEST_CLOB SQL TYPE IS CLOB(2M);

You can specify BLOB or CLOB host variable sizes in kilobytes (K), megabytes (M), Gigabytes (G), or as an integer value. For a Unicode CLOB, use the type DBCLOB. A large object (LOB) host variable is equivalent to this declaration:

DCL 1 name,
     5 name_length      fixed bin(31),
     5 name_data        char(<size>);

where name_data can be an array of CHARs as appropriate if the LOB is greater than 32K.

These examples show how to declare LOB locator host variables.

DCL TEST_BLOB_LOC SQL TYPE IS BLOB_LOCATOR;
DCL TEST_CLOB_LOC SQL TYPE IS CLOB_LOCATOR;

A locator host variable is effectively a pointer to a LOB value, and can generally be used wherever a LOB host variable can be used. The advantage of using locators is that the whole LOB value is not transferred between the application and the server. For example, an application could duplicate a BLOB value from one row into another row.

exec sql
    select lob_col into :test_blob_loc from mytable where key = :k1;
exec sql
    update table2 set lob2_col = :test_blob_loc
    where key2 = :k2;
Parent topic: OpenESQL Support for Oracle PL/I Applications


Date and Timestamp Formatting with OpenESQL for OCI

OpenESQL for OCI supports the regular SQL formatting directives DATE, TIME, DATEDELM, TIMEDELIM and TSTAMPSEP. The default format is the same as ODBC. When an OCI connection opens, OpenESQL executes these Oracle SQL statements to achieve date/time formatting.

alter session set nls_date_format = 'YYYY-MM-DD HH24:MI:SS'
alter session set NLS_TIMESTAMP_FORMAT = 'YYYY-MM-DD HH24:MI:SS.FF9'
alter session set NLS_TIMESTAMP_TZ_FORMAT = 'YYYY-MM-DD HH24:MI:SS.FF9 TZH:TZM'

If you want to use Oracle's default session settings or use alter session statements in your application, you must use -OPTSQL "DATE=EXTERNAL". In this case, OpenESQL passes values directly to and from Oracle without any additional formatting.

Parent topic: OpenESQL Support for Oracle PL/I Applications


Additional Considerations for Oracle

Applications migrating from OpenESQL for ODBC, or from other database systems, should note the following.

Positioned updates and HOLD cursors

OpenESQL for OCI converts positioned updates and deletes to searched updates using Oracle ROWIDs. When a FOR UPDATE cursor is opened, Oracle locks rows up to the first COMMIT. Thereafter OpenESQL still performs positioned updates, but rows fetched after the first COMMIT are not locked.

Scrollable cursors

In OCI, scrollable cursors are always read only. In all other ways, OCI scrollable cursors behave like ODBC keyset cursors. OpenESQL for OCI converts all non-forward only cursors to OCI read only scrollable cursors.

Isolation levels

Oracle OCI does not support read uncommitted isolation and defaults to read committed, based on snapshot/read consistency. However, since Oracle uses row versioning, reads generally do not block. Oracle OCI also does not support repeatable read isolation, so OpenESQL for OCI converts repeatable read isolation to serializable.

EXEC SQL Connect statement processing

  • CONNECT WITH PROMPT is not supported
  • Type 6 connect (user supplied connection string) is not supported
  • Output connection strings are not supported

Dynamic SQL

For dynamic SQL DESCRIBE, OCI may return different data types for NUMBER columns with a scale of 0. Some ODBC drivers may describe these as DECIMAL or NUMERIC. OCI describes them as tinyint (scale <= 2), smallint (scale <= 4), int (scale <= 9), bigint (scale <=18) or decimal (scale > 18).

Parent topic: OpenESQL Support for Oracle PL/I Applications


Recommended OpenESQL Directives for Open PL/I

To provide maximum compatibility with OpenESQL for ODBC applications, simply change -SQL ODBC to -SQL OCI.

This example shows how to use directives for optimum performance of Open PL/I applications with OCI.

-SQL OCI
-OPTSQL "BEHAVIOR=OPTIMIZED"

This example shows the additional SQL directives to use when migrating mainframe DB2 applications.

DATE=USA // or EUR, ISO or JIS as appropriate
DETECTDATE
CHECKDUPCURSOR
CHECKSINGLETON

This example shows the directives to use to provide Oracle date/time formatting.

-SQL OCI
-OPTSQL "DATE=EXTERNAL"
Parent topic: OpenESQL Support for Oracle PL/I Applications


Supported OpenESQL Compiler Options

This table shows supported OpenESQL Compiler Directive Options for SQL ODBC and SQL OCI.

Directives | SQL ODBC Support | SQL OCI Support
ADOPICXISANSI
ALLOWNULLCHAR | X | X
ANSI92ENTRY | X | X
AUTOCOMMIT | X | X
AUTOFETCH | X
BEHAVIOR (includes primitive directives) | X | X
  • DEF_CURSOR
X X
  • IC_FH_ISOLATION
X
  • PF_RO_CURSOR
X X
  • PF_UPD_CURSOR
X X
  • RO_CURSOR
X
  • TRANSACTION
X
  • UPD_CONCURRENCY
X
  • UPD_CURSOR
X
CHECK | X | X
CHECKDUPCURSOR | X | X
CHECKSINGLETON | X | X
CONCAT | X | X
CONNECTIONPOOL | X
CURSORCASE | X | X
DATE | X | X
DATEDELIM | X | X
DB | X | X
DECDEL | X | X
DETECTDATE | X | X
ESQLVERSION | X | X
FIPSFLAG | X | X
GEN-CC2 | X | X
GEN-INIT-FLAG | X | X
GEN-CLASS-VAR | X | X
HSFTRACE | X | X
IGNORE-NESTED | X | X
INIT | X | X
ISOLATION | X
JIT | X | X
MARS | X
NIST | X | X
NOT | X | X
ODBCTRACE | X | X
ODBCV3 | X | X
PARAMARRAY | X
PASS | X | X
PRE | X | X
PREFETCH | X
QUALFIX | X | X
RESULTARRAY | X
STMTCACHE | X | X
TARGETDB | X
TESTSQLSTATE | X | X
TIME | X | X
TIMEDELIM | X | X
THREAD | X | X
TRACELEVEL | X | X
TSTAMPSEP | X | X
USERCURLIB | X
Parent topic: OpenESQL Support for Oracle PL/I Applications


Switch Module Support

This release includes an additional switch module, ESOCIXA.CBL, for use with container-managed applications connecting to Oracle using OCI, and for JES-initiated transactions connecting to Oracle using OCI.

The build script has been updated to provide an additional option, oci, to build this module.

Parent topic: OpenESQL Support for Oracle PL/I Applications


Using the OpenESQL OCI Directive with PL/I: Examples

Compiling

This example compiles a mainframe migrated batch program to maximum performance.

mfplx TESTPGM.PLI –sql oci –optsql
"BEHAVIOR=OPTIMIZED,DATE=USA,DETECTDATE,CHECKDUPCURSOR,CHECKSINGLETON" -ipath
$MFPLI_PRODUCT_DIR/include -isuffix .inc

Compiling and Linking

This example shows three subroutines compiled with a main program that calls routines to object files so it can be linked and bound.

mfplx defplan0.pli -sql oci -optsql "BEHAVIOR=OPTIMIZED" –c -ipath $MFPLI_PRODUCT_DIR/include -isuffix .inc
mfplx defplan1.pli -sql oci -optsql "BEHAVIOR=OPTIMIZED" –c -ipath $MFPLI_PRODUCT_DIR/include -isuffix .inc
mfplx defplan2.pli -sql oci -optsql "BEHAVIOR=OPTIMIZED" –c -ipath $MFPLI_PRODUCT_DIR/include -isuffix .inc
mfplx defplan3.pli -sql oci -optsql "BEHAVIOR=OPTIMIZED" –c -ipath $MFPLI_PRODUCT_DIR/include -isuffix .inc

The link object files are:

ldpli defplan0.obj defplan1.obj defplan2.obj defplan3.obj -out:defplan0.exe

Parent topic: OpenESQL Support for Oracle PL/I Applications


OpenESQL Compiler Options for Open PL/I

Syntax

This syntax sets OpenESQL compiler options for the Open PL/I compiler.

mfplx pliProgName –sql odbc –optsql "SQLPrecompilerOption [...]"

Recommended Options

These OpenESQL compiler options are recommended for PL/I when emulating mainframe settings using SQL.

  • BEHAVIOR=OPTIMIZED
  • CHECKDUPCURSOR
  • CHECKSINGLETON
  • DATE=[LOCAL COUNTRY]
  • TIME=[LOCAL COUNTRY]
  • DETECTDATE

Examples

This example compiles a batch program to qualify tables using MAINFRAME and DATE options.

mfplx TESTPGM.PLI –sql odbc –optsql "BEHAVIOR=OPTIMIZED  DATE=USA"
This example compiles three subroutines and a main program that calls routines to object files so it can be linked.
mfplx testpgm0.pli -sql odbc –optsql  "BEHAVIOR=OPTIMIZED DATE=USA"  –c
mfplx testsub1.pli -sql odbc -optsql  "BEHAVIOR=OPTIMIZED DATE=USA " –c
mfplx testsub2.pli -sql odbc –optsql  "BEHAVIOR=OPTIMIZED DATE=USA " –c
mfplx testsub3.pli -sql odbc -optsql  "BEHAVIOR=OPTIMIZED DATE=USA " –c
This example to links the object files and creates an executable file.
ldpli testpgm0.obj testsub1.obj testsub2.obj testsub3.obj -out:test.exe

Setting Project Options to Compile from Visual Studio

  1. Load the project in Visual Studio.
  2. Select Project > Properties and click the Compile tab.
  3. In the Other options field, type -sql odbc –optsql “SQLPrecompilerOption [...]”.
  4. Press CTRL + S to save your updates.
Parent topic: Open PL/I SQL Options


Open PL/I Compiler Diagnostic Messages

  • Interpreting Diagnostic Messages
Parent topic: Open PL/I User's Guide


Interpreting Diagnostic Messages

The format for Open PL/I compilation diagnostic messages is as follows:

filename (line, col)  :  diagnostic level  MFPLI + diagnostic number + first letter of the diagnostic level :  diagnostic message
filename
The name of the file that caused the diagnostic message.
(line, col)
Line number and column number. If the column number is 0, the column is not available.
diagnostic level
There are five diagnostic levels: Info, Warning, Error, Severe and Abort.
MFPLI + diagnostic number + first letter of the diagnostic level
This consists of "MFPLI", the diagnostic number and the first letter of the diagnostic level (Info - "I", Warning - "W", Error - "E", Severe - "S" and Abort - "A").
diagnostic message
A brief statement of the diagnostic.

Example

hex2.pl1 (10,0) : Severe MFPLI01253S : The first argument of the HEX built-in function must be a variable reference.
Note: An object file is not generated if an error at the Severe or Abort level is encountered.
Parent topic: Open PL/I Compiler Diagnostic Messages
Related information
Compiler Options


Open PL/I Run-time Error Messages

  • Run-time Errors
  • PL/I Run-time Error Codes
Parent topic: Open PL/I User's Guide


Run-time Errors

A run-time error is a program exception that occurs during execution. Some examples of program exceptions are:

  • Overflow on a floating-point computation
  • An invalid I/O operation on a file
  • A UNIX signal
  • An address violation trap
  • An invalid operand to a math routine.

When such errors occur, the LPI run-time system responds by raising an appropriate condition. If the program has established a handler for the particular condition, the handler is invoked; otherwise, the LPI run-time system performs a default action. A program establishes handlers for various conditions by means that differ from language to language: PL/I procedures can establish handlers by using ON-units, FORTRAN procedures can establish handlers for certain kinds of exceptions by using the ERR= and END= specifiers on I/O statements, and other languages provide no means of handling exceptions.

In the absence of a handler, the default action performed by the LPI run-time system for most conditions except the ENDPAGE (f), FINISH, UNDERFLOW, and ERROR conditions is simply to raise the ERROR condition.

  • As the default action for the UNDERFLOW condition, the Open PL/I run-time system substitutes a true zero for the result and continues the computation.
  • As the default action for the ENDPAGE condition, the Open PL/I run-time system does a PUT(f)PAGE.
  • As the default action for the ERROR condition, the LPI run-time system writes a message line to the standard output file (usually the terminal), closes all opened files, and terminates execution of the program.
  • As the default action for the FINISH condition, the Open PL/I run-time system continues execution.

The message line has the following form:

*** Condition ERROR raised

If the ERROR condition was raised as the default action for another condition, the above line is followed by another line:

*** Unhandled condition cccccc[for 000000 on file ffffff] at PC=xxxxxxxx

where

cccccc | Is the name of a condition and indicates the nature of the program exception as described in the remainder of this section.
000000 | Describes the I/O operation.
ffffff | Is the name of the file.
xxxxxxxx | Is the hexadecimal value of the PC at the time the error was detected (usually the address of an instruction in a routine from an LPI run-time library).

If the error is related to an I/O operation on a file, the optional part of the message appears.

I/O errors are program exceptions related to operations on files. End-of-file on sequential input may raise the ENDFILE condition, and errors opening a file usually raise the UNDEFINEDFILE condition. The condition name used by the LPI run-time system for other I/O errors has the form

I0_ERROR_nnn

where nnn is the error code for the particular error: either an LPI run-time system error code or a UNIX system error code.

The AREA condition is raised in two situations: (1) if an attempt is made to allocate a based variable within an area that has insufficient free storage for the allocation, or (2) if an attempt is made to assign one area to another where the maximum size of the source area exceeds that of the target area.

Floating point exceptions raise conditions OVERFLOW, UNDERFLOW, ZERODIVIDE, CONVERSION, INVALID_OPERAND, or INVALID_mmmm, where mmmm is the name of a floating-point function or operation.

OVERFLOW | Indicates that the magnitude of a computational result is too large to represent.
UNDERFLOW | Indicates that the magnitude of a computational result is too close to zero to represent.
ZERODIVIDE | Indicates an attempt to divide by zero (note that the special case of zero divided by zero raises SIGFPE, however). Note: This condition is not recognized in cases where integer division is performed. In this case, the ONCODE for a general computational error (99200) is returned.
CONVERSION | Is raised when a floating-point value cannot be correctly converted to an integer, to or from another floating-point value of a different size, or to or from a character string representation.
INVALID_OPERAND | Results when an operand to a floating-point function (such as SIN, COS, TAN, EXP, and LOG) is out of the range capable of being handled accurately by the system.
INVALID_mmmm | Usually denotes an invalid operand to the indicated floating-point function or operation: the operand is Not-a-Number, +/- infinity, or is outside the mathematical domain of the function or operation.

RTS errors are program exceptions detected by the LPI run-time system not related to I/O. The condition name raised for these errors has the form

 RTS_ERROR_nnn

where nnn is one of the error codes listed in Table B-1. An RTS error related to the conversion of a value from one data type to another is sometimes reported as the CONVERSION condition.

Finally, UNIX signals are errors detected by the system and reported to the program by the system's signaling mechanism. Signaled condition names have the form

SIGxxxx

where xxxx depends on the signal value. The various UNIX signal values are described in your UNIX documentation. On some UNIX systems, floating-point exceptions appear as SIGFPE.

Parent topic: Open PL/I Run-time Error Messages


PL/I Run-time Error Codes

The table below lists the LPI run-time system error codes (100 –170). The UNIX system error codes (001 – 099) correspond exactly to the UNIX system error codes and are listed in your UNIX documentation.

Code | Description
100 | Duplicate record
101 | File not open
102 | Illegal argument
103 | Illegal key descriptor
104 | Too many files open
105 | Bad isam file format
106 | Non-exclusive access
107 | Record locked
108 | Key already exists
109 | Is primary key
110 | End of file reached
111 | No record found
112 | No current record
113 | File locked
114 | File name too long
115 | Can't create lock file
116 | Duplicate record (warning)
117 | Current record pointer undefined
118 | Can't allocate memory
119 | Bad custom collating
120 | Invalid operation
121 | Boundary violation on write
122 | Boundary violation on sequential file
123 | Not available, file locking or closed w/ lock
124 | Inconsistent attributes
125 | Open -APPEND on KEYED file
126 | Open -DAM on non-IDIRECT file
127 | Open -SAM on KEYED file
128 | File not open or is open for output only
129 | File not open or is open for input only
130 | Open on file not yet closed
131 | KEY specified on sequential file
132 | KEY specified on stream file
133 | No KEY specified on KEYED file
134 | Not a PRINT file
135 | Not a STREAM file
136 | CALL dataname name not found
137 | B-format error (35)
138 | BI format error (36)
139 | C format error (32)
140 | E format error (34)
141 | I/O stack overflow
142 | Conversion error
143 | LIST input item too long
144 | Implicit open failed
145 | EOF found while parsing edited input
146 | End of string on GET/PUT string
147 | Invalid format item for GET/PUT string
148 | Invalid format for GET
149 | Cannot initialize RPG screens
150 | File not open for input
151 | REWRITE on input file
152 | File not open on non-optional "sequential"
153 | File open on optional
154 | Sequential error on REW or DELE COBOL85
155 | Sequential error no next record COBOL85
156 | Bad record size on current record
157 | Cannot read log record
158 | Bad log record
159 | Cannot open log file
160 | Cannot write log file
161 | No transaction
162 | No shared memory
163 | No begin work yet
164 | Can't use nfs
165 | Audit trail exists
166 | F format error
167 | Record number too big for data item
168 | Open of wrong file type within transaction
169 | CLOSE REEL on non reel file
170 | No READ or WRITE before DELETE of record
171 | Return from subroutine specified a value
172 | Return from function did not specify a value
173 | Bad definition for creating a VSAM file
174 | No -defext used
175 | SET requires INDEXED or VSAM files
176 | Missing FROM on REWRITE and not VSAM
177 | -ebm requires EBM_ddname usage
178 | Unknown file-type specifier in EBM_ddname
179 | Undefined env var reference within EBM_ddname
180 | Invalid record-length value in EBM_ddname
181 | Unknown record-format in EBM_ddname
182 | File system is out of free space
Parent topic: Open PL/I Run-time Error Messages


Value Table for ONCODE Built-in Function

  • Introduction
  • Table of values returned by ONCODE
Parent topic: Open PL/I User's Guide


Introduction

For more information on ON conditions, see the section ON in the chapter Statements and the section ONCODE Function in the chapter Open PL/I Built-Ins, both in your Open PL/I Language Reference Manual.

Note that the value returned by ONCODE for some conditions is implementation-dependent; in fact, some conditions that occur on one implementation may not be raised at all on another implementation, even by an identical source program run on both implementations. Further, subsequent releases of Open PL/I may change these ONCODE values. Therefore, to make programs more portable, avoid writing Open PL/I programs that depend on specific ONCODE return values to function properly; failing that, use replace constants to represent needed values so that implementation-specific values can be changed easily.

Parent topic: Value Table for ONCODE Built-in Function


Table of values returned by ONCODE

The tables below lists the values (codes) in ascending order, in sections marked by error category.

Code | Meaning
0 | ONCODE has been used outside of an active ON-unit

System-Defined Condition Codes

Code | Meaning
001 – 099 | A UNIX system error has occurred; the value returned corresponds exactly to the UNIX system error codes as listed in your system documentation.
100 – 89999 | An LPI run-time error has occurred; the value returned corresponds exactly to the Open PL/I run-time error codes, as documented in Appendix C. (Note that 89999 is the highest possible error number and that not all error numbers are currently being used.)
9250 | A fetchable procedure was not found.

PL/I Condition Codes

Code | Meaning
99001 | ERROR condition raised by SIGNAL ERROR statement.
99011 | FINISH condition
99020 | ATTENTION condition
99110 | ENDFILE condition
99120 | ENDPAGE condition
99130 | KEY condition
99140 | UNDEFINEDFILE condition
99150 | RECORD condition
99151 | SIZE condition is triggered
99200 | Computational error; some operating systems indicate the precise cause of the error, in which case ONCODE will return the number corresponding to the more specific error description.
99201 | OVERFLOW condition
99202 | UNDERFLOW condition
99203 | ZERODIVIDE condition
99204 | SUBSCRIPTRANGE condition
99205 | CONVERSION condition
99206 | CONDITION condition
99207 | AREA condition
99210 | INVALID OPERAND condition
99211 | INVALID_ADD_SUBTRACT condition
99212 | INVALID_MULTIPLY condition
99213 | INVALID_DIVIDE condition
99214 | INVALID_MOD condition
99215 | INVALID_COMPARISON condition
99251 | INVALID_SQRT condition
99252 | INVALID_ASIN_ACOS condition
99253 | INVALID_ATAN2 condition
99254 | INVALID_LOG condition
99255 | INVALID_POWER condition
99256 | INVALID_ATANH condition
99257 | INVALID_COMPLEX_OPERAND condition
99301 | Stack unwind condition raised during non-local GOTO. This corresponds to the SS$_UNWIND value.
99999 | STRINGRANGE condition

Parent topic: Value Table for ONCODE Built-in Function


National Locale Support

The National Locale Support (NLS) facility provides a means of adapting your program to the character code set for a particular country, without the need for your application to know what these are in advance. This facility is also useful in English-speaking countries for handling codepages, collating upper- and lower-case letters correctly, selecting the appropriate currency symbol and selecting alphabetic extenders (for the $, # and @ signs) for PL/I identifier names.

The NLS facility provides you with the means to use codepages appropriate for your country when using UPPERCASE, LOWERCASE, PLIASCII, and PLIEBCDIC built-ins.

NLS can also be used to create messages in your language if messages for your language are provided by the appropriate release of the product.

  • Compiling Programs with NLS
  • Setting Up the National Locale Environment
  • Using the LANG Environment Variable
  • Running Your NLS Program
  • NLS Initialization
  • NLS Operations
Parent topic: Open PL/I User's Guide


Compiling Programs with NLS

Use the following compiler options to obtain NLS support:

  • -currency_symbol to control the currency symbol
  • -names to specify alphabetic extenders that can be used in the formation of PL/I identifier names
  • -or_symbol to specify the or symbol used as an "or" or (when paired) "concatenate" operator. This feature while not strictly NLS related does facilitate use of alternate symbols
  • -not_symbol to specify the not symbol used as the "not" operator. This feature while not strictly NLS related does facilitate use of alternate symbols
Parent topic: National Locale Support


Setting Up the National Locale Environment

Before you run a program with the facility, you must define your locale. A locale is the combination of language, territory and codepage. The locale used by the run-time system is initially set to the value of the regional settings for the operating system.

Parent topic: National Locale Support


Using the LANG Environment Variable

You define a locale using the LANG environment variable. LANG is set using the operating system command SET:

set LANG=language

You can also set this to obtain compile-time messages in a language of your choice assuming the messages in your language are provided by the release of the product you are using.

Parent topic: National Locale Support


Running Your NLS Program

You run programs containing NLS in the same way as you run programs without it. When the program runs:

  • The operating system's regional settings are used to determine which language environment to set up for this program. Use the LANG environment variable to provide the desired settings.
  • The NLS facility performs various operations in accordance with the rules of the language specified in the LANG environment variable.
Parent topic: National Locale Support


NLS Initialization

The run-time system initializes the NLS facility only once during an application's run. It uses the operating system's regional settings to determine which language environment to set up for this program using the LANG environment variable.

The run-time system uses the same language environment for any subsequent programs within the application which are compiled using NLS facilities.

If an error occurs during this initialization process, for example the language specified in the LANG environment variable is not supported, the run-time system reports the error:

40  National Language initialization not set up correctly

and terminates its run.

You can also receive this error if the LANG environment variable was set up by a third party product in a format different from that used by this PL/I system. If this occurs, use the COBLANG environment variable instead of the LANG environment variable.

If the run-time system cannot find the NLS run-time support modules, it issues the message:

46  NLS support module not found

and terminates its run.

Parent topic: National Locale Support


NLS Operations

When you run a program which has been compiled with the NLS directive set, certain operations are carried out in accordance with the rules of the language specified in the LANG environment variable.

Other language-dependent features, such as the currency character are controlled by the appropriate compiler option.

Certain NLS definitions have characters other than the ASCII characters 0-9 defined as numerics. Such characters are not valid in numeric picture strings, nor can they be used in numeric operations. Note that in all NLS operations, a numeric item must be formed only from the ASCII digits 0-9, with or without the ASCII signs "+" or "-" as well as other picture characters. There is no means of automatically converting the NLS representation to the ASCII equivalent.

The following are not affected by NLS:

  • String comparisons
  • SORT and MERGE Key Comparisons when SORT facility is in use
  • Case Conversion via UPPERCASE and LOWERCASE built-ins
  • Character conversion between EBCDIC and ASCII via PLIASCII and PLIEBCDIC built-ins
  • Collating Sequence Operations
  • Editing and computations on PICTURE data
Warning: Mixing programs with and without NLS can have unpredictable results
Parent topic: National Locale Support


Character Sets

  • Using the EBCDIC Character Set
    Describes how the EBCDIC character set is supported by the Open PL/I compiler and run time.
  • EBCDIC/ASCII Equivalents
Parent topic: Open PL/I User's Guide


Using the EBCDIC Character Set

The Open PL/I compiler and run time support character data encoded in EBCDIC format as well as ASCII format. For EBCDIC, this essentially means that the user program understands all character data as EBCDIC. Humans see all character data as readable text when it is read from input devices and written to display devices. When EBCDIC data is written to a file or read from a file, the data is always encoded as EBCDIC

Compiling a program in EBCDIC mode does not mean that the source file is in EBCDIC format. The source file is always in ASCII format, and character string literals such as 'abc' are converted to EBCDIC by the compiler. Run time support in EBCDIC mode likewise maintains all character data in EBCDIC format, and only translates to and from ASCII for human readable input or output devices.

For any given program, it is expected that all modules are compiled in either ASCII mode or EBCDIC mode.

The following compiler switches are supported:

-ascii | all character data in the user program is stored in ASCII format (default)
-ebcdic | all character data in the user program is stored in EBCDIC format

These examples show how the compiler treats character data in EBCDIC mode:

'abc' | stored as 0x818283
'abc ' | stored as 0x81828340
'abc 'E | stored as 0x81828340
'abc 'A | stored as '0x61626320
dcl s char (4) init (''); | stored as 0x40404040
dcl s char (4) init (''E); | stored as 0x40404040 (''E the null string padded with 4 EBCDIC spaces 0x040)
dcl s char (4) init (''A); | stored as 0x40404040 (''A the null string padded with 4 EBCDIC spaces 0x040)

These examples show how the compiler treats character data in ASCII mode:

'abc' | stored as 0x616263
'abc ' | stored as 0x61626320
'abc 'E | stored as 0x81828340
'abc 'A | stored as '0x61626320
dcl s char (4) init (''); | stored as 0x20202020
dcl s char (4) init (''E); | stored as 0x20202020 (''E the null string padded with 4 ASCII spaces 0x020)
dcl s char (4) init (''A); | stored as 0x20202020 (''A the null string padded with 4 ASCII spaces 0x020)
Note: In the above examples, the postfix characters for "E and "A are superfluous because the null string is padded with spaces accordingly with EBCDIC or ASCII mode.

When compiling in EBCDIC or ASCII mode through a server, output is dependent on the MF_CHARSET setting on the server. This table shows expected output formats of SYSPRINT for EBCDIC or ASCII-compiled programs based on the MF_CHARSET setting on the server.

Program Compiled | Server Running As | DCB | Expected Format of SYSPRINT
ASCII | ASCII | SYSOUT=* | ASCII
EBCDIC | EBCDIC | SYSOUT=* | EBCDIC
ASCII | ASCII | SYSOUT=*,DCB=(RECFM=LSEQ) | ASCII
EBCDIC | EBCDIC | SYSOUT=*,DCB=(RECFM=LSEQ) | ASCII
ASCII | EBCDIC | SYSOUT=*,DCB=(RECFM=LSEQ) | ASCII

Note that EBCDIC datasets are in EBCDIC and display correctly in ESMAC. LSEQ Datasets are flipped to ASCII and display correctly in ESMAC

Parent topic: Character Sets


EBCDIC/ASCII Equivalents

Index | EBCDIC (Hex) | Character | ASCII (Hex) | Notes
000 | 00 | NUL | 00 | null
001 | 01 | SOH | 01 |
002 | 02 | STX | 02 |
003 | 03 | ETX | 03 |
004 | 04 | PF | EC |
005 | 05 | HT | 09 | horizontal tab
006 | 06 | LC | CA |
007 | 07 | DEL | 7F | delete
008 | 08 |  | E2 |
009 | 09 |  | D2 |
010 | OA | SMM | D3 |
011 | OB | VT | OB | vertical tab
012 | OC | FF | OC | form feed
013 | OD | CR | OD | carriage return
014 | OE | SO | OE |
015 | OF | SI | A9 |
016 | 10 | DLE | 10 |
017 | 11 | DC1 | 11 |
018 | 12 | DC2 | 12 |
019 | 13 | TM | 13 |
020 | 14 | RES | EF |
021 | 15 | NL | C5 |
022 | 16 | BS | 08 |
023 | 17 | IL | CB |
024 | 18 | CAN | 18 |
025 | 19 | EM | 19 |
026 | 1A | CC | DC |
027 | 1B | CU1 | D8 |
028 | 1C | IFS | 1C |
029 | 1D | IGS | 1D |
030 | 1E | IRS | 1E |
031 | 1F | IUS | 1F |
032 | 20 | DS | B7 |
033 | 21 | SOS | B8 |
034 | 22 | FS | B9 |
035 | 23 |  | BB |
036 | 24 | BYP | C4 |
037 | 25 | LF | OA | line feed (new line)
038 | 26 | ETB | 17 |
039 | 27 | ESC | 1B |
040 | 28 |  | CC |
041 | 29 |  | CD |
042 | 2A | SM | CF |
043 | 2B | CU2 | DO |
044 | 2C |  | D1 |
045 | 2D | ENQ | 05 |
046 | 2E | ACK | 06 |
047 | 2F | BEL | 07 | bell
048 | 30 |  | D9 |
049 | 31 |  | DA |
050 | 32 | SYN | 16 |
051 | 33 |  | DD |
052 | 34 | PN | DE |
053 | 35 | RS | DF |
054 | 36 | UC | E0 |
055 | 37 | EOT | 04 | end transmission
056 | 38 |  | E3 |
057 | 39 |  | E5 |
058 | 3A |  | E9 |
059 | 3B | CU3 | EB |
060 | 3C | DC4 | B0 |
061 | 3D | NAK | B1 |
062 | 3E |  | 9E |
063 | 3F | SUB | 1A |
064 | 40 | SP | 20 | space
065 | 41 |  | C9 |
066 | 42 |  | 83 |
067 | 43 |  | 84 |
068 | 44 |  | 85 |
069 | 45 |  | A0 |
070 | 46 |  | F2 |
071 | 47 |  | 86 |
072 | 48 |  | 87 |
073 | 49 |  | A4 |
074 | 4A | ¢ | D5 |
075 | 4B | . | 2E | period
076 | 4C | < | 3C |
077 | 4D | ( | 28 |
078 | 4E | + | 2B |
079 | 4F | I | 7C |
080 | 50 | & | 26 |
081 | 51 |  | 82
082 | 52 |  | 88 |
083 | 53 |  | 89 |
084 | 54 |  | 8A |
085 | 55 |  | A1 |
086 | 56 |  | 8C |
087 | 57 |  | 8B |
088 | 58 |  | 8D |
089 | 59 |  | E1
090 | 5A | ! | 21 |
091 | 5B | $ | 24 |
092 | 5C | * | 2A |
093 | 5D | ) | 29 |
094 | 5E | ; | 3B | semicolon
095 | 5F | ¬ | 7E | ASCII tilde (~)
096 | 60 | - | 2D | hyphen
097 | 61 | / | 2F |
098 | 62 |  | B2 |
099 | 63 |  | 8E |
100 | 64 |  | B4 |
101 | 65 |  | B5 |
102 | 66 |  | B6 |
103 | 67 |  | 8F |
104 | 68 |  | 80 |
105 | 69 |  | A5 |
106 | 6A |  | B3 |
107 | 6B | , | 2C | comma
108 | 6C | % | 25 |
109 | 6D | _ | 5F | underscore
110 | 6E | > | 3E |
111 | 6F | ? | 3F |
112 | 70 |  | BA
113 | 71 |  | 90 |
114 | 72 |  | BC |
115 | 73 |  | BD |
116 | 74 |  | BE |
117 | 75 |  | F3 |
118 | 76 |  | C0 |
119 | 77 |  | C1 |
120 | 78 |  | C2 |
121 | 79 | ´ | 60 | accent grave
122 | 7A | : | 3A | colon
123 | 7B | # | 23 |
124 | 7C | @ | 40 |
125 | 7D | ' | 27 | apostrophe (accent acute)
126 | 7E | = | 3D |
127 | 7F | " | 22 | quotation mark
128 | 80 |  | C3 |
129 | 81 | a | 61 |
130 | 82 | b | 62 |
131 | 83 | c | 63 |
132 | 84 | d | 64 |
133 | 85 | e | 65 |
134 | 86 | f | 66 |
135 | 87 | g | 67 |
136 | 88 | h | 68 |
137 | 89 | I | 69 |
138 | 8A |  | AE |
139 | 8B |  | AF |
140 | 8C |  | C6 |
141 | 8D |  | C7 |
142 | 8E |  | C8 |
143 | 8F |  | F1 |
144 | 90 |  | F8 |
145 | 91 | j | 6A |
146 | 92 | k | 6B |
147 | 93 | l | 6C |
148 | 94 | m | 6D |
149 | 95 | n | 6E |
150 | 96 | o | 6F |
151 | 97 | p | 70 |
152 | 98 | q | 71 |
153 | 99 | r | 72 |
154 | 9A |  | 5E | ASCII caret ( ^ )
155 | 9B |  | A7 |
156 | 9C |  | 91 |
157 | 9D |  | CE |
158 | 9E |  | 92 |
159 | 9F |  | 0F |
160 | A0 |  | E6 |
161 | A1 |  | A6 |
162 | A2 | s | 73 |
163 | A3 | t | 74 |
164 | A4 | u | 75 |
165 | A5 | v | 76 |
166 | A6 | w | 77 |
167 | A7 | x | 78 |
168 | A8 | y | 79 |
169 | A9 | z | 7A |
170 | AA |  | AD |
171 | AB |  | A8 |
172 | AC |  | D4 |
173 | AD |  | 5B | ASCII left bracket ( [ )
174 | AE |  | D6 |
175 | AF |  | D7 |
176 | B0 |  | 9B |
177 | B1 |  | 9C |
178 | B2 |  | 9D |
179 | B3 |  | FA |
180 | B4 |  | 9F |
181 | B5 |  | 15 |
182 | B6 |  | 14 |
183 | B7 |  | AC |
184 | B8 |  | AB |
185 | B9 |  | FC |
186 | BA |  | AA |
187 | BB |  | FE |
188 | BC |  | E4 |
189 | BD |  | 5D | ASCII right bracket (])
190 | BE |  | BF |
191 | BF |  | E7 |
192 | C0 |  | 7B | ASCII left brace ( { )
193 | C1 | A | 41 |
194 | C2 | B | 42 |
195 | C3 | C | 43 |
196 | C4 | D | 44 |
197 | C5 | E | 45 |
198 | C6 | F | 46 |
199 | C7 | G | 47 |
200 | C8 | H | 48 |
201 | C9 | I | 49 |
202 | CA |  | E8 |
203 | CB |  | 93 |
204 | CC |  | 94 |
205 | CD |  | 95 |
206 | CE |  | A2 |
207 | CF |  | ED |
208 | D0 |  | 7D | ASCII right brace ( } )
209 | D1 | J | 4A |
210 | D2 | K | 4B |
211 | D3 | L | 4C |
212 | D4 | M | 4D |
213 | D5 | N | 4E |
214 | D6 | O | 4F |
215 | D7 | P | 50 |
216 | D8 | Q | 51 |
217 | D9 | R | 52 |
218 | DA |  | EE |
219 | DB |  | 96 |
220 | DC |  | 81 |
221 | DD |  | 97 |
222 | DE |  | A3 |
223 | DF |  | 98 |
224 | E0 |  | 5C | ASCII backslash ( \ )
225 | E1 |  | F0 |
226 | E2 | S | 53 |
227 | E3 | T | 54 |
228 | E4 | U | 55 |
229 | E5 | V | 56 |
230 | E6 | W | 57 |
231 | E7 | X | 58 |
232 | E8 | Y | 59 |
233 | E9 | Z | 5A |
234 | EA |  | FD |
235 | EB |  | F5 |
236 | EC |  | 99 |
237 | ED |  | F7 |
238 | EE |  | F6 |
239 | EF |  | F9 |
240 | F0 | 0 | 30 |
241 | F1 | 1 | 31 |
242 | F2 | 2 | 32 |
243 | F3 | 3 | 33 |
244 | F4 | 4 | 34 |
245 | F5 | 5 | 35 |
246 | F6 | 6 | 36 |
247 | F7 | 7 | 37 |
248 | F8 | 8 | 38 |
249 | F9 | 9 | 39 |
250 | FA |  | DB |
251 | FB |  | FB |
252 | FC |  | 9A |
253 | FD |  | F4 |
254 | FE |  | EA |
255 | FF |  | FF |
Parent topic: Character Sets


Environment Variables

  • Environment Variables Summary
Parent topic: Open PL/I User's Guide


Environment Variables Summary

This is a list of the most commonly used environment variables.

Variable | Description
ES_PL1_MFFH | Enables Micro Focus File Handler to perform all Open PL/I I/O operations. The default value is Y. If it is set to N, then all I/O are routed to old Liant file handlers.
ES_PL1_MFFH_JCL | Enables you to run Open PL/I programs that access JCL data definitions. The default value is N.
ES_PLI_SUPPORT | Tells the CICS Emulation that it needs to load its subsystem support for PL/I user programs. The default value is N.
MFPLI_PRODUCT_DIR | The location of the Open PL/I installation. It is used to find files needed for compiling and linking.
MFPLI_CONFIG_DIR | The location of the PLIDEBUG.DAT file. The folder defined by the MFPLI_PRODUCT_DIR environment variable is searched before using this location.
Parent topic: Environment Variables


Migration to Micro Focus File Formats

  • Overview
  • Reasons for Migrating to Micro Focus File Formats
  • Determine What File Formats You Are Using
  • Liant Indexed (aka) IBM/Informix CISAM
  • Liant Indexed (aka) IBM/Informix CISAM Conversion Process
  • Liant Variable Length Sequential Conversion Process
  • Liant Relative Record Conversion Process
  • Appendix - Unload Program
  • Appendix - Load Program
  • Appendix - Sample Shell Script to Build/Run
  • Appendix - Sample extfh.cfg
Parent topic: Open PL/I User's Guide


Overview

This guide shows you how to migrate your data to Micro Focus file formats so that it can be processed and manipulated using standard processes.

Parent topic: Migration to Micro Focus File Formats


Reasons for Migrating to Micro Focus File Formats

Micro Focus has its own file handler called Micro Focus ISAM that it has developed and enhanced for over two decades to provide file processing support for all Micro Focus COBOL-based applications. Within version 8.1 of Open PL/I we have therefore switched to using this core technology from Micro Focus rather than relying on the 3rd party file handler for Indexed files that was used originally within Open PL/I.

This will enable Micro Focus to provide ongoing support for all the file processing requirements of our Open PL/I customers from a single technology shared with all Micro Focus COBOL customers, but it does require data to be unloaded from original files formats and loaded into new Micro Focus file formats.

Parent topic: Migration to Micro Focus File Formats


Determine What File Formats You Are Using

These are the available file formats:

  • Line Sequential - no conversion necessary
  • Liant Sequential Fixed Length - no conversion necessary
  • Liant Indexed (aka) - IBM/Informix CISAM - conversion necessary *
  • Liant Relative Record - conversion optional **
  • Liant Sequential (Variable Length) - conversion optional **
Parent topic: Migration to Micro Focus File Formats
* Conversion is necessary if utilizing PLI IO Verbs.
** Conversion is only necessary if you intend to utilize the data within Micro Focus Enterprise Server and/or share the files with Micro Focus COBOL Programs.


Liant Indexed (aka) IBM/Informix CISAM

If you are using native PL/I I/O Verbs, you must convert data to Micro Focus Indexed Format.

If you are using IBM/Informix "IsXXXXX" APIs, you have two options:
  • Convert API calls to native PL/I I/O Verbs (and convert data)
  • Purchase a copy of CISAM from IBM and continue to use your existing datasets and "IsXXXXX" APIs.
    ( isaddindex () isbuild () isclose () isdelcurr () isdelete () iserase () isindexinfo () isopen () isread () isrelease () isrewcurr () isrewrite () ISRELOCK () isstart () isdef () iswrite () )
Parent topic: Migration to Micro Focus File Formats


Liant Indexed (aka) IBM/Informix CISAM Conversion Process

Unload is a very simple generic program needing only maximum record length and file names.

Load is a very simple generic program needing only maximum record length, file names, and key offset and length. Sample code is provided in Appendix A.

Load requires use of extfh.cfg to prevent null bytes from being stripped from output.

Note: SCALARV in the diagram above stands for SCALARVARYING.

The source programs in Appendix A are small and very simple. If you find that you have a large number of files that need to be converted, then one approach would be to use a shell script to generate the unload and load programs.

The easiest way to automate the process and generate the conversion programs via scripts would be to place all of the %REPLACE statements and the VSAM File Declarations in a PLI %INCLUDE. You should then be able to compile up the programs and be off and running.

In our testing of this process we had both the Open PL/I 7.4 Compiler and Open PL/I 8.1 Compiler and RTS Environments running side by side with no problems.

Parent topic: Migration to Micro Focus File Formats


Liant Variable Length Sequential Conversion Process

Load and Unload programs are very simple generic programs needing only maximum record length and file names to be provided. Sample code provided in Appendix A can be easily modified.

Load requires use of extfh.cfg to prevent null bytes from being stripped from output.

Note: SCALARV in the diagram above stands for SCALARVARYING.
Parent topic: Migration to Micro Focus File Formats


Liant Relative Record Conversion Process

Load and Unload programs are very simple generic programs needing only maximum record length and file names to be provided. Sample code provided in Appendix A can be easily modified.

Load requires use of extfh.cfg to prevent null bytes from being stripped from output.

Note: SCALARV in the diagram above stands for SCALARVARYING.
Parent topic: Migration to Micro Focus File Formats


Appendix - Unload Program

unload_liant_files: proc() options(main);
%replace MAX_REC_LEN               by 100;
%replace MAX_REC_LEN_SV            by 102;
%replace INPUT_TITLE               by 'liantCISAM';
%replace OUTPUT_TITLE              by 'fixed_cisam.dat';
 dcl inputfile    file record         env(vsam  recsize( MAX_REC_LEN ) );
 dcl outputfile    file record output env(f recsize( MAX_REC_LEN_SV ));

 dcl record_buff char(MAX_REC_LEN ) varying;
 dcl fixed_buf   char( MAX_REC_LEN_SV ) based(addr(record_buff));
 dcl vsam_buff   char( MAX_REC_LEN );

 on endfile(inputfile) goto doneinputfile;

 open file(inputfile) title(INPUT_TITLE) keyed sequential input;
 open file(outputfile) title(OUTPUT_TITLE);

 substr(fixed_buf, 2, length(fixed_buf) - 2) = '';
 read file(inputfile) into(record_buff);
 do while(1);
    write file(outputfile) from (fixed_buf);
    substr(fixed_buf, 2, length(fixed_buf) - 2) = '';
    read file(inputfile) into(record_buff);
 end;

doneinputfile:
 close file(inputfile);
 close file(outputfile);
end;
Parent topic: Migration to Micro Focus File Formats


Appendix - Load Program

load_microfocus_files: proc() options(main);

%replace MAX_REC_LEN               by 100;
%replace MAX_REC_LEN_SV            by 102;
%replace INPUT_TITLE               by 'fixed_cisam.dat';
%replace OUTPUT_TITLE              by 'microfocusIndexed.dat';
%include ‘vsamrec.in’;

 dcl inputfile    file record input env(f recsize( MAX_REC_LEN_SV ));
 dcl outputfile    file record
     env(vsam  recsize( MAX_REC_LEN ) keyloc(11) keylength(10));
 dcl 1 fixed_buf based(addr(in_rec)),
       5 fixed_buf_len  fixed bin(15),
       5 fixed_buf_data char( MAX_REC_LEN );
 dcl in_rec    char( MAX_REC_LEN ) varying;
 on endfile(inputfile) goto done;
 open file(inputfile) title(INPUT_TITLE);
 open file(outputfile) title(OUTPUT_TITLE) keyed sequential output;
 read file(inputfile) into(fixed_buf);
 do while(1);
    string(vsam_rec) = in_rec;
    write file(outputfile) from (vsam_rec) keyfrom(last_name);
    read file(inputfile) into(fixed_buf);
 end;
done:
 close file(inputfile);
 close file(outputfile);
end;
Parent topic: Migration to Micro Focus File Formats


Appendix - Sample Shell Script to Build/Run

echo ‘Solaris Sparc Shell Script’
rm liant*
rm microfocus*
rm fixed_*

lpiplx -deb -defext -cisam create_liant_files.pli -o create_liant_files
lpiplx -deb -defext -cisam test_liant_files.pli   -o test_liant_files
lpiplx -deb -defext -cisam unload_liant_files.pli -o unload_liant_files

mfplx  -deb -defext load_microfocus_files.pli -o load_microfocus_files
mfplx  -deb -defext test_microfocus_files.pli -o test_microfocus_files

echo 'Running create_liant_files'
./create_liant_files
echo 'Running test_liant_files'
./test_liant_files
echo 'Running unload_liant_files'
./unload_liant_files
echo 'Running load_microfocus_files'
./load_microfocus_files
echo 'Running test_microfocus_files'
./test_microfocus_files
Parent topic: Migration to Micro Focus File Formats


Appendix - Sample extfh.cfg

[XFH-DEFAULT]
IDXFORMAT=8
INSERTNULL=OFF
Parent topic: Migration to Micro Focus File Formats


Troubleshooting

Micro Focus enterprise products include a varied set of facilities for problem analysis. These diagnostic facilities are the result of numerous implementations, and the realization that different sorts of problems can occur, each requiring its own type of approach. We will try to suggest here which diagnostic facility to use for which problem.

As a minimum, we recommend that anyone involved in Enterprise Server implementations should know, for each diagnostic tool or technique:

  • What it does
  • How to configure it
  • What the output is that is produced, and where to find it

After identifying the appropriate facility, we aim to help any users of the enterprise products to set up and run the diagnostics, and then either analyze the output themselves or send them to Micro Focus for help from our Support teams.

Depending on the type of problem, you might need to use several of these diagnostic facilities simultaneously. For instance, a regular start point is the console log. However, this rarely shows the full problem, so very often you need a trace output and dump to complete the analysis. The console log might identify the failing process, and the trace and dump output will show the detail of what the process was doing and how it was interacting with the other processes if that is critical. Alone, these might be of little use, but together they can pinpoint what led to the failure.

Although it is well understood that during project implementation and production running, speed can be of the essence to complete the project or bring the business system back up, if Micro Focus is to help, it is vital that the diagnostic output be gathered in its entirety and treated as data of very high value in its detail and its completeness.

Please treat this documentation as a reference, and bear in mind that each problem is different and will require its own approach to diagnosis, so choose from the facilities detailed here based on what you believe to be the type of problem.

  • Diagnostics in Enterprise Server
  • Minimum Diagnostic Configuration Recommendations for Production Systems
  • Production System Failure Data Capture
  • Reporting a Problem
  • Specific Troubleshooting Advice
Parent topic: Micro Focus Enterprise Server 2.3 Update 1 for Windows


Diagnostics in Enterprise Server

Enterprise Server contains logs that are generally always written to, and which require little or no configuration. For more detailed tracing, additional parameters and configuration files can be set to capture a much more detailed set of diagnostic information.

  • Default Logs
    These logs require no configuration as they are enabled for at least some logging by default.
  • Configurable Traces and Diagnostics
    These require some additional configuration before they are active.
  • Security Tracing
    Security trace messages can be written to the console.log, the MFDS journal.log, and the AUX trace.
  • Non-Micro Focus Diagnostics
    The utilities available with the operating system or available from third parties are often very useful in providing additional information that can complete the diagnostic picture or indeed identify specific problems directly, for example, with the environment setup or network.
Parent topic: Troubleshooting


Default Logs

These logs require no configuration as they are enabled for at least some logging by default.

However, additional configuration is available for some of them, for example, to control their size and content.

  • Console Log
    This is the most important log in the system.
  • Micro Focus Communications Server (MFCS) log.html
    This logs messages from the communications manager process(es) and any associated listeners.
  • Micro Focus Directory Server (MFDS) journal.log
    The MFDS process provides an information repository, and is one of the first things to be accessed during region startup.
Parent topic: Diagnostics in Enterprise Server


Console Log

This is the most important log in the system.

It contains the region activity since startup and hence shows what happened leading up to a failure.

You should review this log first, to see which errors have occurred, when they occurred, and which process was responsible. The Process ID and time from this log lets entries in other logs be associated with this particular error or entry in the console log.

Parent topic: Default Logs


Micro Focus Communications Server (MFCS) log.html

This logs messages from the communications manager process(es) and any associated listeners.

It shows specific information related to the addresses and port numbers used.

Parent topic: Default Logs


Micro Focus Directory Server (MFDS) journal.log

The MFDS process provides an information repository, and is one of the first things to be accessed during region startup.

If security is enabled, this log can also help show whether and which connections to MFDS have been successful or are rejected.

Note: The MFDS process is a single process that provides an information repository for the entire Enterprise Server installation. This means, therefore, that it interacts with all defined regions running on this machine, and hence entries in the journal.log could be from more than one region.
Parent topic: Default Logs


Configurable Traces and Diagnostics

These require some additional configuration before they are active.

A wide range of settings is available to let you collect specific and relevant information.

Note: This can result in very large files, so you should check disk space when configuring these traces.
  • Auxiliary Trace
    This provides a trace of activity over a time period within the main CAS facilities.
  • CASDUMP
    A system dump provides a "time slice" view of resources within the system at the time that the dump is requested, and is valid only for that specific time.
  • CTF Trace
    This is the primary logging mechanism for the COBOL system. It logs what happens in most user programs and what is happening within the internal CAS processes themselves. For example, JCL and the compiler/ debugger.
  • MFCS Connector Tracing
    Each MFCS listener has an associated connector module.
  • Memory Strategy
    Memory strategy can be enabled where memory corruption is detected or suspected.
  • Historical Statistical Facility (HSF)
    Provides the ability to record statistics related to the time spent in a COBOL program.
  • Core on Error
    This feature causes a program core dump to be generated when that program causes an exception.
  • Fileshare Trace
    This facility provides specialist tracing of the transactional file handler technology.
  • External File Handler Trace
    The File Handler module can be configured to generate trace information that can be later replayed and analyzed using the associated utility program.
  • XA Switch Module Tracing
    Additional trace can be enabled to provide more detail regarding the XA Resource Manager interface.
Parent topic: Diagnostics in Enterprise Server


Auxiliary Trace

This provides a trace of activity over a time period within the main CAS facilities.

Because it runs while the system is running, it can affect the performance of the system, and is therefore very configurable in order to record the specific types of events that might be needed for different types of problems. Ideally, production systems should be able to perform adequately with at least the minimum tracing enabled.

Auxiliary trace is usually configured from the Enterprise Server Admin Console (i.e. ‘Aux Trace Active’), but can also be configured using the ‘CTRA’ transaction from a 3270 session. Trace information is written to the trace files CASAUXTA and CASAUXTB, and the amount of information output is controlled by the setting of specific trace flags (e.g. Application (API), Storage Control (SCP), and Application Container (RTS)).

To view a video on the Micro Focus YouTube channel, on how to enable AUX tracing for Enterprise Server, click here.

Parent topic: Configurable Traces and Diagnostics


CASDUMP

A system dump provides a "time slice" view of resources within the system at the time that the dump is requested, and is valid only for that specific time.

Taking the dump should not have any performance impact on the system. A manual dump can be taken at any time (with no additional configuration required) from the command line or the ESMAC interface. However, a region should be configured to generate a system dump whenever a System Abend occurs. This is usually configured in the Enterprise Server Admin Console (i.e. ‘Dump on System Abend’).

Additionally, “Dump on Transaction Abend” can be set in ESMAC so that any abending transactions will also cause a dump to be generated.

Dump information will be written to the current casdump file (casdumpa.rec, casdumpb.rec or casdumpx.rec), and includes the current contents of process memory, server control blocks and the local and system trace tables.

We recommend you take a dump for most problems when they occur, and whilst the system is in the failed state.

Parent topic: Configurable Traces and Diagnostics
Related reference
MQ Listener (listener-name)


CTF Trace

This is the primary logging mechanism for the COBOL system. It logs what happens in most user programs and what is happening within the internal CAS processes themselves. For example, JCL and the compiler/ debugger.

It records activity over a period of time, and is enabled via a separate configuration file. CTF tracing can be restricted to specific components or modules, and certain elements within these components. The level of detail included in the trace can be configured for each component if required.

To view a video on the Micro Focus YouTube channel, on how to enable CTF tracing for Enterprise Server, click here.

Parent topic: Configurable Traces and Diagnostics


MFCS Connector Tracing

Each MFCS listener has an associated connector module.

They can be specified via the "listener type" setting in the MFDS GUI. In turn, most connector modules have optional tracing that is configured in the Configuration Text area for that listener, by using "trace=y" in a [Trace] section.

Parent topic: Configurable Traces and Diagnostics


Memory Strategy

Memory strategy can be enabled where memory corruption is detected or suspected.

When it is enabled, it allows the COBOL sub-system to verify/validate memory addresses as they are used by a program. This means that when memory operations occur, the system is able to validate that only the assigned memory has been used. If this is not the case, an exception will be generated at the point that the corruption is detected. The Memory Strategy facility provides a fine-grained control over which processes are checked, and the extent of the checking that is done: this keeps the overhead of enabling Memory Strategy to a minimum.

Parent topic: Configurable Traces and Diagnostics


Historical Statistical Facility (HSF)

Provides the ability to record statistics related to the time spent in a COBOL program.

The Historical Statistical Facility provides the ability to record statistics related to the time spent in a COBOL program, and the time that parts of that program spent in CICS API commands/ tasks, SQL operations and JCL jobsteps, as well as associated file and TSQ accesses.

Parent topic: Configurable Traces and Diagnostics


Core on Error

This feature causes a program core dump to be generated when that program causes an exception.

Once a core dump is generated, it can be loaded into the development environment where the offending line of code should be shown, so the call stack and values of variables can be examined. It is most useful in a production environment where it is unlikely that a debugger can be dynamically attached: the core dump can be obtained and then analyzed on another system. The .IDY file(s) must be available for the programs that fail, as this allows the core dump to show as much information as possible regarding the state of the program at failure time. Without the .IDY file(s), only a limited amount of diagnostics can be performed.

Parent topic: Configurable Traces and Diagnostics


Fileshare Trace

This facility provides specialist tracing of the transactional file handler technology.

Fileshare is a transactional filehandler for VSAM and other Micro Focus COBOL files, and Fileshare trace would be required only if you have fileshare configured for use. Generally, Fileshare trace should be used only for specific cases during testing because it can have a great impact on performance.

Parent topic: Configurable Traces and Diagnostics


External File Handler Trace

The File Handler module can be configured to generate trace information that can be later replayed and analyzed using the associated utility program.

This would show information such as filenames accessed, and the operation used (for example, Open or Read). More detailed information can also be generated for specific file operations (for example, access mode and file format).

Parent topic: Configurable Traces and Diagnostics


XA Switch Module Tracing

Additional trace can be enabled to provide more detail regarding the XA Resource Manager interface.

The console.log will contain basic errors and other messages relating to XA resources. Additional AUX and CTF trace flags can be set to output more detailed XA messages to the relevant trace files.

Parent topic: Configurable Traces and Diagnostics


Security Tracing

Security trace messages can be written to the console.log, the MFDS journal.log, and the AUX trace.

You configure detailed security tracing in the relevant Configuration Text areas for:

  • MFDS and globally for all regions (‘security’ button in left hand pane) via:
    • the default Enterprise Server Security tab
    • each Security Manager definition
  • individual regions via:
    • the region’s Security tab (from Server > Properties tabs)

The options available for Security Manager tracing depend on the External Security Manager (ESM) module used by that manager. In addition, the security AUX trace flag (saf) can be enabled for region-specific security tracing.

Note: Problems with initial access to MFDS (for example, to start a region) will be logged in the MFDS journal. However, trace must first be set up in the External Security Manager (ESM) to output these messages.

Security tracing can have a significant effect on performance so should not be left on in a production system.

  • Security Auditing
Parent topic: Diagnostics in Enterprise Server


Security Auditing

The security audit facility is sometimes useful for diagnostic purposes. It maintains a record of security decisions (user sign-on succeeded, resource access request denied, etc). It needs the Audit Manager to be running: you can start it from the command line, or as a service on Windows or a daemon on UNIX. You configure it with a configuration file that is specified with the ‘-c <filename>’ option.

Parent topic: Security Tracing


Non-Micro Focus Diagnostics

The utilities available with the operating system or available from third parties are often very useful in providing additional information that can complete the diagnostic picture or indeed identify specific problems directly, for example, with the environment setup or network.

On Windows, you might need to obtain additional tools to those included in your operating system. In particular, a suite of tools originally supplied by Sysinternals.com and now distributed by Microsoft include most of the useful tools, for example, procmon).

On UNIX, tools such as strace and truss might be provided as optional installation components, or are otherwise available for download and installation.

The following external utilities have proved useful in providing supporting information when a problem occurs, or in investigating problems that would be exposed directly to the operating system:

  • Windows
    • Process Monitor (Procmon – real-time process activity)
    • Netstat (TCP/UDP port connection information)
    • Process Explorer (open handles and DLLs), also (from command line):
      • Handle (open handles/files in the OS)
      • listDLLs (DLLs loaded in a process)
    • Depends (dependent modules and exported functions)
    • Windows Task Manager
    • Windows Resource Manager
    • Windows Performance Monitor (+SCOM)
    • Windows Event Manager
    • TCPview and Wireshark (TCP endpoints, addresses and traffic)
    • Debugging Tools for Windows (ADplus, Windbg)
    • Microsoft Network Monitor (NetMon) (can trace VPN networks)
    • Rawcap (can trace the loopback interface)
  • UNIX
    • strace/truss
    • lsof (list open files)
    • netstat (TCP/UDP port connection information)
    • ipcs (interprocess communications - for shared memory etc)
    • ulimit (limits on open files)
Parent topic: Diagnostics in Enterprise Server


Minimum Diagnostic Configuration Recommendations for Production Systems

We recommend that you run your production system with some diagnostics switched on. In this way, unexpected problems can be investigated when they first occur. 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 re-occur.

‘Dump on System Abend’ should always be enabled in an Enterprise Server region, along with some Auxiliary tracing. The following level of diagnostics is the minimum we recommend for running in production systems.

From the Diagnostics tab on the Enterprise Server Admin Console:

  • Check Dump on System Abend
  • Check Auxiliary Trace Active
  • Check the Task Control (KCP) and Application (API) trace flags

We strongly recommend that you also enable the ‘core_on_error’ facility so that application core dumps are created whenever there is a crash: see the topic Producing a Core Dump for Run-time Errors.

Parent topic: Troubleshooting


Production System Failure Data Capture

For all troubleshooting exercises, it is essential you gather as much information as possible about the state of the enterprise server region when the problem occurred and about the events leading up to the problem. This should include the date/time the problem occurred, and observations on what was happening in the system, how long it had been running, what the symptoms were, and how/where these were observed.

When a problem occurs, you must capture and provide specific logs, traces and dumps, and ideally the contents of various configuration files, directories (for example, MFDS), and the output from a number of operating system tools. This should be done as soon as possible after the failure occurs.

Diagnostic Collection Script

Use the MFESdiags diagnostic script to collect this information automatically.

On Windows, the script is MFESdiags.cmd which can be obtained from SupportLine. You can run it from any command prompt or from Windows Explorer. You will be prompted for the region name, and you should zip up the resultant data collection directory and attach it to an incident.

On UNIX, the script is mfesdiags.sh which can be obtained from SupportLine. Transfer it to the UNIX machine and give it the 'execute' permission (for example, chmod +x mfesdiags.sh). Run the script in the COBOL/Enterprise Server environment. It will prompt for the relevant region name for which to collect diagnostics, and will generate mfesdiags.trz which you should attach to an incident.

Both the UNIX and Windows scripts invoke the relevant 'mfsupport' utility which collects information about the operating system and machine hardware, along with details relating to Micro Focus products you have installed.

As a minimum, for example if MFESdiags is not used to collect the data, you should collect and provide the following items as soon as possible after a failure. You can do this simply by zipping or 'tar'ing the contents of the system/region directory.

  • console.log
  • log.html or log-*.html (for communications problems)
  • journal.log (for MFDS/security problems)
  • Any casdump or aux traces
  • MFSupportInfo (on Windows)
  • mfsupport (on Unix)

The MFESdiags data collection script collects all of the above, and other useful information details, as follows:

  • All files from the Enterprise Server's System/Region Directory, including:
    • console.log and console.bak. The communications process log log.html or log-*.html
    • Any trace diagnostic datasets, casauxta.rec and casauxtb.rec
    • Any system abend dumps, casdumpa.rec, casdumpb.rec or casdumpx.rec
    • Any HSF output files (*.csv)
  • The output from MFSupportInfo (Windows)/mfsupport (Unix), which contains product and system information
  • The Resource Definition File (RDO/RDT), dfhdrdat.
  • The Directory Server (MFDS) log file
  • The Directory Server configuration directory
  • Additional configuration files (if they exist) including:
    • mf-server.dat
    • mf-client.dat
    • CTF Trace configuration file
    • COBCONFIG (core_on_error) configuration file
    • EXTFH file handler configuration file
  • A list of system processes running on the machine
  • A list of network connections and listening sockets using netstat
  • Windows Service information for MFDS (on Windows)
  • Windows System and Application Event logs (on Windows)
  • A list of shared memory areas and semaphores (on UNIX)
  • A list of open files (on UNIX)
Note: The MFESdiags script will collect CTF trace logs if the region is configured to generate CTF trace. See the CTF Trace topic for configuration details.
Parent topic: Troubleshooting


Reporting a Problem

The following topics describe best practices in providing information when a problem occurs and an incident needs to be raised.

  • How to Report a Support Incident (SI)
  • Different Types of Incident
  • Managing the Incident
  • Important Considerations for Incidents
  • Naming Conventions for Diagnostic Collection
Parent topic: Troubleshooting


How to Report a Support Incident (SI)

All incidents should be reported either through the SupportLine website or via your local Freephone Support number – this is shown on the SupportLine website.

We recommend you report incidents through the website. General instructions are:

  1. Go to http://supportline.microfocus.com and login (at the left in the margin).
  2. If you do not have a Web ID to login, register for one (on the Log In page below the login fields).
  3. Report the SI online (under “My Incidents”).
  4. Give the incident an informative short description (see the topic Providing an Informative Short Description).
  5. Attach all relevant information that might be useful in supporting the issue diagnosis. They type of problem you are encountering affects this, but in general it should include the following:
    • The MFESdiags output as described above
    • Step–by–step instructions to reproduce the error
    • Any sample programs that can be used to reproduce the problem. Ideally, provide a zip file containing everything necessary to build any program(s)
    • Any directives used if there are problems with compilation
    • Make a note of any Micro Focus consulting FDS or other utility that is being used and attach to the incident if possible
  • Providing an Informative Short Description
Parent topic: Reporting a Problem


Providing an Informative Short Description

Include explicit and concise information in the Short Description to make it specific rather than general. For example, write:

“Source won’t compile, getting error code ###“

or

“Enterprise Server shows error code ### during restart”

rather than a more general (and less useful) description like:

“Error with source compile”

or

“Enterprise Server is crashing”

Parent topic: How to Report a Support Incident (SI)


Different Types of Incident

We recognize that different types of problem occur with Micro Focus products. In this section, we address five particular types; there are undoubtedly more, but this advice covers the majority. The five types we concentrate on are:

  • Compiler-related Incidents
  • Debugging Failures
  • Reproducible Run-time Failures
  • Unpredictable Run-time Failures
  • Performance Issues
Parent topic: Reporting a Problem


Compiler-related Incidents

For this type of issue, the minimum that we request you supply is:

  • A cut-down of the particular piece of code that is failing; some compiler failures can be related to size of Working Storage etc, so if it is not possible to cut it down, supply the full program. As a tip, if you compile to .lst and supply this to us, this will automatically include all copybooks, and show the directives being used.
  • If you do not supply a .lst, please supply the directives that you are compiling with.
  • Detail the failure symptom or mode.
  • Explain or reference any supporting material if the issue relates to code that you believe should compile successfully. For instance, under a particular standard or model.
Parent topic: Different Types of Incident


Debugging Failures

If you encounter a failure during a debug session in the IDE, we suggest the following as the minimum to complete a high-quality incident report:

  • A copy of the source code that shows the failure, cut down as much as possible - as with compiler issues, you might want to supply a listing (.lst) file.
  • Take the run-time diagnostics of the failure, pulled together using MFESdiags.
  • Associated debugging files, including the IDE CTF trace files and the Java "hot spot" log (for the Eclipse IDE).
Parent topic: Different Types of Incident


Reproducible Run-time Failures

If you have a failure at run time that is consistently reproducible then we suggest that when reporting the incident you include the following:

  • The code necessary to reproduce the failure – this should be cut down as much as possible.
  • Any data needed to reproduce the failure.
  • The details of what the failure actually is; the run-time error message, a corruption, or that the code is not behaving as you expect.
  • Set the appropriate first point of failure diagnostics; adjust them based on your own judgement as to what you believe will help us to understand and diagnose the problem – for instance, if it is a File Handler problem, refer to that section for possible additional tracing; if a memory corruption seems to be occurring, consider the memory strategy settings.
  • Collect the output from the run, using the MFESdiags script.
  • Report the problem to Micro Focus, and upload the diagnostics captured by the MFESdiags script, using the naming conventions recommended.

We would also be happy to hear of any hypothesis or theory that you have that might help us to address the failure more quickly.

Parent topic: Different Types of Incident


Unpredictable Run-time Failures

When tuning production systems, or during their implementation, failures can be seen that do not occur with any predictable regularity or under definable circumstances. It is these types of failures that require the first point of failure diagnostics to be captured and reported to Micro Focus along with full context and detail of the failure.

We recommend that all systems be run, during implementation or in production, with the minimum diagnostic settings configured. Other diagnostic settings should be configured depending on the failure scenario, symptoms, and area of technology. This document provides information on what is available, for instance for communications tracing, Fileshare/File Handler tracing and other areas.

When the failure re-occurs, you should use the MFESdiags script to gather the diagnostic files and report the incident to Micro Focus, uploading these diagnostics following the naming convention set out in this section.

The long description in particular should provide as much context and detail as possible, including chronology and timeline. For further information, see Important Incident Considerations.

Parent topic: Different Types of Incident
Related reference
Important Incident Considerations


Performance Issues

A lot of projects identify performance issues at some point and occasionally slow-downs can occur in production systems.

These are actually two types of issues and these should be approached differently. For performance testing during implementation, we recommend that the following protocol be followed as closely as possible:

  1. Define what acceptable performance is. This can be:
    • the same as a previous platform (maybe, for example, as the IBM mainframe)
    • as fast as a set of particular users find acceptable
    • some other criteria.

    This gives you a target to aim for, and to measure how close you are to being complete.

  2. Identify a representative benchmark program or execution scenario.
  3. Create a spreadsheet, and in it record for each run of the benchmark:
    • The actual benchmark program that is run for this test – you should run a ‘baseline’ to be the start point for tuning hardware, compilations, execution setup etc, and for measuring the impact.
    • The results; elapsed time, I/O time, or whichever type of data you want to measure.
    • The variables that are adjusted for each run; perhaps the programs are compiled with different directives, perhaps the hardware setup is adjusted, perhaps the database is moved from a remote machine to a local machine.
    • Any comments or observations on each run; did it improve performance or not? Did it seem to show up some type of anomaly or restrictions in scaling?

For performance slowdowns that occur post-production, the obvious question to ask is ‘what has changed?’ This might be upgraded hardware – we have seen that adding hardware power does not always improve performance, indeed it can slow it down if the architecture or system setup is not configured to take advantage of it. If nothing seems to have changed, look for whatever else might be running on the system at the time that the slowdown occurs; we frequently have customers find that anti-virus software or mass searches are being done on a machine when performance slows down.

Another very important aspect of performance to consider is the virtual machine environment, if it is part of the setup. Experience has shown that running with a VM can add up to 20% overhead to performance from straight hardware; it is very important to employ a VM consultant to look at the configuration and setup of the VM that is in use to run the Enterprise Server environment.

Parent topic: Different Types of Incident


Managing the Incident

Reply to the incident within the Web Site with your Web ID, so that any answers are logged immediately, and the incident owner is aware you’ve replied to the questions sent to you.

Remember to continue to give detailed information and background regarding new situations that are being reported, or when responding to requests for further tests/information.

Parent topic: Reporting a Problem


Important Considerations for Incidents

High quality initial incident reporting can considerably shorten the time that it takes to a get to a solution. A high quality incident should have:

  • An accurate short description of the symptom
  • A long description that is full and complete, and covers the circumstances and context of the failure
  • As much context and detail as possible. If you are unsure whether it is relevant, provide it anyway
  • Important details such as chronology, symptoms, configuration, workload levels and third party software involved

Always include relevant diagnostics on the initial report. A good set of diagnostics is:

  • Uploaded to the Micro Focus ftp site or attached to the incident (see the topic Naming Conventions for Diagnostic Collection)
  • Complete – includes traces, dumps, console and other relevant logs
  • From the same failure – submitting a console log from Tuesday, a trace from Wednesday and a dump from Thursday does not help as none of the process numbers or details will match
  • Inclusive of specific failure details (probably in the long description) with particular attention to the date/time of the failure, when it started, what symptoms it demonstrated, whether it recovered or required manual intervention

If you believe that a problem reoccurs on a system:

  • Always capture a new set of diagnostics – multiple sets may help us see ‘patterns’
  • Update the existing incident number that the problem was reported on
  • Add comments to the incident detailing the date/time of the new failure, why you think it is a reoccurrence of the same problem, and as much other context on this new failure as possible, including the similarity with previous failures
  • Supply the diagnostics to Micro Focus using the naming convention for the diagnostics collections and/or other files detailed in the next topic
Parent topic: Reporting a Problem


Naming Conventions for Diagnostic Collection

When MFESdiags is used, the data collected will be in a folder or zip file with a name containing the date and time that the collection was done, for example:

2013-06-05_14-49-36-42-snapshot(.zip)

Please ensure that this convention is carried through so that any additional data provided is identified in the same way.

The incident number should also be included in the diagnostics collection filename whenever information is uploaded to the FTP site (rather than being attached directly to an incident).

This naming convention is particularly important when multiple failure data collections are taken for the same incident and problem - sometimes it can take several failures to help in pattern identification for a complex problem resolution.

Parent topic: Reporting a Problem


Specific Troubleshooting Advice

There are numerous topics on troubleshooting throughout your documentation, giving advice on specific areas of the product.

Parent topic: Troubleshooting
Related reference
Mainframe Access Troubleshooting
EJB Troubleshooting
Enterprise Server Troubleshooting
XA Troubleshooting
JCL Troubleshooting
MSS Troubleshooting
CCITCP2 Troubleshooting
Troubleshooting a Secure Connection
Troubleshooting CICS Web Interface Servers


Copyright and Legal Information

  • Copyright and Trademarks
  • Secure Communications (SSL) Legal Information
  • NET SNMP Copyright
Parent topic: Micro Focus Enterprise Server 2.3 Update 1 for Windows


Copyright and Trademarks

Copyright © Micro Focus 1984-2016. 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®, DB2®, MQSeries®, RACF® and WebSphere® 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. Such portions have been modified by Micro Focus.

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. Contact your Micro Focus representative if you require access to the modified Apache Software Foundation source files.

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.

2016-07-10

Parent topic: Copyright and Legal Information


NET SNMP Copyright

---- Part 1: CMU/UCD copyright notice: (BSD like) -----

       Copyright 1989, 1991, 1992 by Carnegie Mellon University

          Derivative Work - 1996, 1998-2000
Copyright 1996, 1998-2000 The Regents of the University of California

             All Rights Reserved

Permission to use, copy, modify and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appears in all copies and
that both that copyright notice and this permission notice appear in
supporting documentation, and that the name of CMU and The Regents of
the University of California not be used in advertising or publicity
pertaining to distribution of the software without specific written
permission.

CMU AND THE REGENTS OF THE UNIVERSITY OF CALIFORNIA DISCLAIM ALL
WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL CMU OR
THE REGENTS OF THE UNIVERSITY OF CALIFORNIA BE LIABLE FOR ANY SPECIAL,
INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
FROM THE LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

---- Part 2: Networks Associates Technology, Inc copyright notice (BSD) -----

Copyright (c) 2001-2003, Networks Associates Technology, Inc
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

*  Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

*  Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

*  Neither the name of the Networks Associates Technology, Inc nor the
   names of its contributors may be used to endorse or promote
   products derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS
IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

---- Part 3: Cambridge Broadband Ltd. copyright notice (BSD) -----

Portions of this code are copyright (c) 2001-2003, Cambridge Broadband Ltd.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

*  Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

*  Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

*  The name of Cambridge Broadband Ltd. may not be used to endorse or
   promote products derived from this software without specific prior
   written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER ``AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

---- Part 4: Sun Microsystems, Inc. copyright notice (BSD) -----

Copyright © 2003 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
California 95054, U.S.A. All rights reserved.

Use is subject to license terms below.

This distribution may include materials developed by third parties.

Sun, Sun Microsystems, the Sun logo and Solaris are trademarks or registered
trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

*  Redistributions of source code must retain the above copyright notice,
    this list of conditions and the following disclaimer.

*  Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

*  Neither the name of the Sun Microsystems, Inc. nor the
    names of its contributors may be used to endorse or promote
    products derived from this software without specific prior written
    permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS
IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

---- Part 5: Sparta, Inc copyright notice (BSD) -----

Copyright (c) 2003-2005, Sparta, Inc
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

*  Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

*  Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

*  Neither the name of Sparta, Inc nor the names of its contributors may
   be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS
IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

---- Part 6: Cisco/BUPTNIC copyright notice (BSD) -----

Copyright (c) 2004, Cisco, Inc and Information Network
Center of Beijing University of Posts and Telecommunications.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

*  Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

*  Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

*  Neither the name of Cisco, Inc, Beijing University of Posts and
   Telecommunications, nor the names of their contributors may
   be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS
IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

---- Part 7: Fabasoft R&D Software GmbH & Co KG copyright notice (BSD) -----

Copyright (c) Fabasoft R&D Software GmbH & Co KG, 2003
oss@fabasoft.com
Author: Bernhard Penz bernhard.penz@fabasoft.com

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

*  Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

*  Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

*  The name of Fabasoft R&amp;D Software GmbH & Co KG or any of its subsidiaries,
   brand or product names may not be used to endorse or promote products
   derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER ``AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
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.
  • Command line options can be specified as /option or -option.
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.
  • The keys described in this book are not available in all environments. When there is a reference to use of a key such as a status or function key, this refers to the logical press and release of this key, rather than physical keystroke. If your environment does not support the key given, please refer to your accompanying Read Me for the equivalent key.
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 Enterprise Developer to a non-default installation directory, adjust the path specifications accordingly.
  • All path specifications show default paths for installation on the Windows 7 operating system. If you have installed on an alternative operating system, adjust the path specifications accordingly.
  • All path specifications show the physical directory name. This might be different than the paths shown by default in the Windows Explorer address field. For example, a folder listed as Computer > (OS)C: > Users > Public > Public Documents, or something similar, in the Explorer address field usually describes a physical location of c:\users\public\documents. To see the physical location, click the address field in Explorer. You also see the physical path at a command prompt.
  • Some path specifications use an environment variable to represent dynamic drive and directory names. For example, if your %PUBLIC% environment variable is set to c:\users\public, then substitute c:\users\public in place of a %PUBLIC% specification in the documented path.
  • Some path specifications use the %ProgramFiles(x86)% environment variable to represent the drive and directory containing your program files for both 32-bit and 64-bit machines. If you are running on a 32-bit machine, resolve this to the value of the %ProgramFiles% environment variable.
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 Enterprise Server 2.3 Update 1 for Windows


Configure PVCS Drives

Defines a drive letter for use within tools supporting SourceConnect technology. The drive letter is mapped to a PVCS configuration file.

Select a drive letter that you want to map to PVCS. Existing real drives are not selectable.

To access PVCS, you would specify the fully qualified location of the PVCS configuration file to be used for your environment. You must be using PVCS version 5.2 or greater. Optionally, a promotion group or version label can be specified as well.

Important: if you are using the version label operand for the PVCS drive, then all files will be read from the labelled version level, but any updates will create a distinct branch, that the user is responsible to merge, using PVCS tools, when complete.
Related concepts
Configuring the Cache
Related information
Adding a Mainframe Node
Configure Mainframe Drives


JCLAM0240S MANAGEMENTCLASS class-name not found

A definition of the managementclass has not been found in SMS.

Resolution:

Add the required managementclass definition to SMS. See Using SMS MGMT Classes.

Parent topic: JCLAM0231 -


SORT000 - SORT099

  • SORT009U job-number job-name SORT TERMINATED - ERROR ACCESSING MFJSORTM.DAT
    The message file cannot be found or it cannot be opened.
  • SORT012U job-number job-name SYSIN DATASET 'DATASET' EMPTY
    MFJSORT has found the specified SYSIN data set to be empty. Processing is terminated.
  • SORT013U job-number job-name I/O ERROR ON DATASET 'DATASET'
    An I/O error has occurred on the specified data set.
  • SORT014U job-number job-name STATUS = FILE STATUS
    The specified file status values indicate the cause of the I/O error reported in message SORT013U.
  • SORT015U job-number job-name COMMAND STATEMENT ERROR(S) DETECTED
    Errors have been detected during SYSIN command statement processing.
  • SORT016I job-number job-name SORTTEMP DATASET ALLOCATED TO 'FILE'
    The temporary sort work file has been allocated to the specified file. The temporary file name is obtained from the operating system and appended with a $WK file name extension.
  • SORT019I job-number job-name KEY LENGTH TRUNCATED TO 4096 BYTES
    The concatenated key length exceeds 4096 bytes. Processing continues, however the sort/merge operation uses only the first 4096 bytes of the key field(s) specified.
  • SORT020U job-number job-name SORT(EXTSM) FAILED – SORT ENGINE STATUS = EXTSM STATUS
    The size of the files which can be sorted or merged by MFJSORT(EXTSM) is determined by the record length, number of sort fields, sort field lengths, the amount of memory available, and the amount of disk space available for virtual paging.
  • SORT033I job-number job-namenumber RECORDS MERGED
    This message indicates the number of records actually written to the SORTOUT output data set by the MERGE function.
  • SORT034I job-number job-namenumber RECORDS COPIED
    This message indicates the number of records actually written to the SORTOUT output data set by the COPY function.
  • SORT035U job-number job-name SORTIN DSORG OR RECFM MISSING
    The record format for the SORTIN data set is missing.
  • SORT036U job-number job-name SORTIN RECORD LENGTH MISSING OR INVALID
    The record length for the SORTIN data set is missing.
  • SORT037U job-number job-name SYSIN RECFM 'FORMAT'' INVALID
    The record format for the SYSIN data set is invalid.
  • SORT038U job-number job-name SORTIN RECFM 'FORMAT' INVALID
    The record format for the SORTIN data set is invalid.
  • SORT039U job-number job-name SORTOUT RECFM 'FORMAT' INVALID
    The record format for the SORTOUT data set is invalid.
  • SORT040U job-number job-name SORT TERMINATED BY E15 'PROGRAM'
    The user E15 exit has requested termination of the sort/merge operation.
  • SORT041U job-number job-name SORT TERMINATED BY E35 'PROGRAM'
    The user E35 exit has requested termination of the sort/merge operation.
  • SORT042U job-number job-name MEMORY ALLOCATION FAILURE
    The system has run out of memory during the sort process.
  • SORT043U job-number job-name TOO MANY OUTFIL FILES SPECIFIED
    The limit of 16 OUTFIL files has been exceeded.
  • SORT044U job-number job-name TOO MANY 'USE' FILES SPECIFIED
    The limit of 16 USE files has been exceeded (non-emulation mode).
  • SORT045U job-number job-name TOO MANY 'GIVE' FILES SPECIFIED
    The limit of 16 GIVE files has been exceeded (non-emulation mode).
  • SORT090U job-number job-name SORT TERMINATED - MISSING SYSOUT
    The DD statement for the SYSOUT data set cannot be located.
  • SORT091U job-number job-name SORT TERMINATED - MISSING SYSIN
    The DD statement for the SYSIN data set cannot be located.
  • SORT092U job-number job-name SORT TERMINATED - MISSING SORTOUT
    The DD statement for the SORTOUT data set cannot be located.
  • SORT093U job-number job-name SORT TERMINATED - MISSING SORTIN OR SORTIN01
    The DD statement for a SORTIN or SORTIN01 data set cannot be located.
  • SORT094U job-number job-name SORT TERMINATED - MISSING SORTOFnn
    The DD statement for a SORTOF data set referenced by the OUTFIL control statement cannot be located.
  • SORT095U job-number job-name SORT TERMINATED – BAD DATA IN 'CHANGE' FIELD
    Input data did not match any of the CHANGE find-constants and the NOMATCH option was not specified.
  • SORT096U job-number job-name SORT TERMINATED – MISSING FNAMES DATASET 'DATASET'
    The DD statement for the FNAMES data set cannot be located.
Parent topic: SORT - MFJSORT Error Messages


JCLAM0180 - JCLAM0230

  • JCLAM0180S Unexpected return code return-code from jseb-func-enq-ds
    Indicates an internal error detected by jseb-func-enq-ds.
  • JCLAM0181S Unexpected return code % from jseb-func-deq-ds
    Indicates an internal error detected by jseb-func-deq-ds.
  • JCLAM0182U Unexpected return code % from jseb-func-info-job
    Indicates an internal error detected by jseb-func-info-job.
  • JCLAM0183S Character set mismatch. Copied without conversion
    You are trying to copy an ASCII dataset to an EBCDIC one, or vice versa.
  • JCLAM0184I OS Copy used to perform this REPRO
    Informational only.
  • JCLAM0185S OS Copy operation for this REPRO failed with RC=return-code
  • JCLAM0186I Incompatible data set attributes. OSCOPY ignored.
    A full copy operation was done, instead of using the copy facility provided by the operating system as you requested.
  • JCLAM0187I Dataset dsname is still allocated to (at least) ...
    Dataset dsname is still allocated to (at least) one or more DDnames.
  • JCLAM0188I DD DDNAME. This may cause unexpected results later.
    Emitted in conjunction with JCLAM0187I and reports on a DDNAME that still has a dataset name allocated to it.
  • JCLAM0189I(00) - Dataset attributes assumed to match PC file "pcFileName".
    A new VSAM dataset has been allocated using the same name as that specified by pcFileName, which already exists. The IDCAMS allocation assumes that the new VSAM dataset has attributes that match the specified PC file.
  • JCLAM0221S Insufficient authority to define new dataset %
    Lack of permissions to perform this action.
  • JCLAM0222S Insufficient authority to read dataset %
    Lack of permissions to perform this action.
  • JCLAM0223S Insufficient authority to update dataset %
    Lack of permissions to perform this action.
  • JCLAM0224E Insufficient authority to delete dataset %
    Lack of permissions to perform this action.
  • JCLAM0225E Insufficient authority to alter/change dataset %
    Lack of permissions to perform this action.
  • JCLAM0226U Insufficient authority for SYSPRINT dataset %
    Lack of permissions to perform this action.
  • JCLAM0227U Insufficient authority for SYSIN dataset %
    Lack of permissions to perform this action.
  • JCLAM0228I Record n out of key sequence.
    The record has a key that is less than or equal to the key of the previous record.
  • JCLAM0229E Record n out of key sequence.
    The record has a key that is less than or equal to the key of the previous record.
  • JCLAM0230S Insufficient authority to use PCDSN dataset %
    Lack of permissions to perform this action.
Parent topic: JCLAM Error Messages


JCLAM0140 - JCLAM 0159

  • JCLAM0140I job-number job-name LASTCC set to number
    The condition code LASTCC has been set to the specified value.
  • JCLAM0141I job-number job-name MAXCC set to number
    The condition code MAXCC has been set to the specified value.
  • JCLAM0142S job-number job-name AVERAGE RECORD LENGTH INVALID
    The average record length must be greater than 0 bytes but not greater than 32760 bytes.
  • JCLAM0143S job-number job-name MAXIMUM RECORD LENGTH INVALID
    The maximum record length must be greater than 0 bytes but not greater than 32760 bytes.
  • JCLAM0144S job-number job-name KEY LENGTH INVALID
    The primary key length must be greater than 0 but not greater than 64.
  • JCLAM0145S job-number job-name KEY OFFSET INVALID
    The key offset plus the key length exceeds the defined record length.
  • JCLAM0146E job-number job-nameNUMBER DUPLICATE KEYS
    The specified number of duplicate keyed records have NOT been replaced by the REPRO command.
  • JCLAM0147W job-number job-name 00000000 DATASETS LISTED
    No datasets have been listed by the LISTCAT command.
  • JCLAM0148E job-number job-name NO MATCHING ENTRIES [ENTRYNAME]
    There are no entries in the catalog which match the pattern entry name specified for the delete request.
  • JCLAM0149S INVALID QUOTED LITERAL
    The literal contains an uneven number of quotation marks.
  • JCLAM0150S ERROR. FILE IS EMPTY
    You are trying to copy from an empty file.
  • JCLAM0151S job-number job-name Invalid dataclass name "name"
    The specified data class name is not legal or is longer than 8 characters.
  • JCLAM0152S job-number job-name Dataclass "name" does not exist
    This specified data class has not been defined to this system.
  • JCLAM0153S job-number job-name UNEXPECTED MVSSMS FUNC_GU RETCODE [number]
    Unexpected return code received from the MVSSMS (the data class manager).
  • JCLAM0154S job-number job-name THEN MUST FOLLOW AN IF COMMAND
    The IF command must be followed by the THEN keyword.
  • JCLAM0155I job-number job-name Remainder of command stream ignored
    The remainder of the command stream has been ignored.
  • JCLAM0156I job-number job-name CANCEL COMMAND EXECUTED
    The CANCEL command has been executed.
  • JCLAM0157S job-number job-name Space (CYL or TRK or REC) missing
    Space, using one of the specified keywords, must be specified for a new data set.
  • JCLAM0158S job-number job-name RECORG for input and output data set incompatible
    Either the output file is RRDS and is not empty, or the input file is not RRDS.
  • JCLAM0159S job-number job-name Primary quantity invalid
    The primary quantity is not a number.
Parent topic: JCLAM Error Messages


JCLAM0227U Insufficient authority for SYSIN dataset %

Lack of permissions to perform this action.

Resolution:

Contact your system administrator.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0231 -

  • JCLAM0231E Unable to acquire exclusive lock on dataset "dataset-name"
    The action requires an exclusive lock on the named dataset but was unable to obtain it.
  • JCLAM0236E Duplicate record "record number"
  • JCLAM0238S (JCLAM0238E) Invalid data type for ALTER dataset
  • JCLAM0239I Dataset attribute attribute-name unchanged
  • JCLAM0240S MANAGEMENTCLASS class-name not found
Parent topic: JCLAM Error Messages


JCLCM0128S Host dataset %1$s unexpectedly deleted by alien job.

Explains purpose of topic. Written as sentence fragment. Contains no more than two sentences.
Parent topic: JCLCM0000 - JCLCM0199


JCLCM0130W LRECL of host RECFM V dataset %1$s assumed to be 255.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0129W LRECL of host RECFM F dataset %1$s assumed to be 80.

Parent topic: JCLCM0000 - JCLCM0199


JCLUT0010E

Message

INPUT DD(%1$s) on DSD CARD not found

Where %1$s is Dataset name.

Message Information

The INPUT dataset specified on the DSD card could not be found.

Resolution

Check for a missing DD card defining the dataset or a mismatch of dataset names.

Parent topic: JCLUT Error Messages


JCLCM0122S Incorrect password caused SAF failure on the host.

Parent topic: JCLCM0000 - JCLCM0199


Why You Should Use the Assess Application Migration Tool

When considering application migration from mainframe DB2 to SQL Server, you need answers to these important questions:
  • How fast can I get my application migrated, up, and running on SQL Server?
  • How do I figure out how heavily my application relies on mainframe technology?
  • How can I eventually eliminate all reliance on mainframe technology such that my application uses SQL Server exclusively?
The Assess Application Migration tool helps you to analyze your COBOL and PL/I code with these questions in mind, and provides valuable information that guides you in determining the best migration option for your application. Using HCOSS, you have several options. You can:
Migrate your code as-is to SQL Server
Use this option if your goal is to get up and running as quickly as possible with SQL Server, without a dependency on mainframe compatibility or behavior. This is a great option if you have few statements to remediate, and you want to eliminate mainframe behavior dependency immediately.
Migrate converted DB2 statements to SQL Server statements
Use this option if you want to identify all SQL DB2 statements that require conversion to SQL Server statements to ensure 100% SQL Server compatibility after migration, and manually convert that code before migration. Contact Micro Focus SupportLine for more information on this approach.
Migrate your original code using HCOSS without the BIND option
Use this option if your goal is to get up and running as quickly as possible with SQL Server, but you do not want to BIND your application. This approach requires that you remediate SQL package and plan statements.
Migrate your original code using full HOCSS functionality
Use this option if your goal is to get up and running as quickly as possible with SQL Server. This option exploits all HCOSS functionality and ensures that your application runs with mainframe compatibility.
We also recommend that you use the Assess Application Migration tool Data Analysis feature to analyze your schema extract files and identify structures that are not supported by SQL Server, or that could require manual modification before HCOSS can accurately transfer the data to SQL Server. Data analysis includes the identification of:
  • SQL data types
  • SQL Stored Procedures written in an unsupported application language
  • SQL Sequences
  • Defined Global Tables
  • SQL ALIAS objects
  • SQL SYNONYMS
Related concepts
HCOSS Toolset
Migrating Applications
Application Migration Process
Migration Scenarios
Related tasks
To analyze schema extract data
Related reference
Data Analysis tab


JCLUT0012E "keyword" is invalid keyword value.delimiter, descriptor or type is improper, or duplicated

Message

"%1$s" is invalid keyword value.delimiter, descriptor or type is improper, or duplicated

Where %1$s is a keyword or command.

Message Information

The command or keyword is invalid.

Resolution

Check the keyword, particularly its use with other keywords, and correct the command statement.

Parent topic: JCLUT Error Messages


JCLAM0238S (JCLAM0238E) Invalid data type for ALTER dataset

A duplicate record error has been generated. The specified ALTER command is not appropriate for this dataset type.

Resolution:

Apply the changed property to the appropriate dataset type.

Example

For example, it is not possible to ALTER the MGMTCLASS for a VSAM ALTERNATE INDEX. Instead, you need to apply the changed MGMTCLASS to the CLUSTER and then it is propagated to all elements.

Parent topic: JCLAM0231 -


JCLCM0125E %1$s is not supported.

Parent topic: JCLCM0000 - JCLCM0199


Source Code tab

Source File
The full path to and filename of the selected source code file. If you have processed the assessment, this tab displays the converted code. Otherwise, it displays the original source code.
Next EXEC SQL
Search down and jump to the next EXEC SQL statement in the source code, wrapping back to the beginning of the file when it reaches the end.
Previous EXEC SQL
Search up and jump to the previous EXEC SQL statement in the source code, wrapping back to the end of the file when it reaches the beginning.
Related concepts
Assess Application Migration Tool
Related tasks
To assess application migration


SORT100 - SORT199

  • SORT100E job-number job-name MISSING OPERATOR
    The SYSIN command statement does not contain a valid operator.
  • SORT101E job-number job-name MALFORMED OPERATOR
    The SYSIN command statement operator (at the specified column) is invalid. A space must separate the operator from any operands.
  • SORT102E job-number job-name EXPECTED OPERAND MISSING
    A required operand is not present on the command statement.
  • SORT103E job-number job-name INVALID OPERATOR 'OPERATOR'
    The command statement operator (at the specified column) is invalid.
  • SORT104E job-number job-name INVALID OPERAND KEYWORD 'OPERAND'
    The command statement operand (at the specified column) is invalid.
  • SORT105E job-number job-name EXPECTED CONTINUATION NOT PRESENT
    The command statement contains a continuation character in column 72, but the continuation text has not been found.
  • SORT106E job-number job-name FIELD FORMATS IMPROPERLY SPECIFIED
    The field format is incorrectly coded as a field-specific operand (for example, FIELDS=1,5,CH,A) and also as a global operand (for example, FORMAT=CH).
  • SORT107E job-number job-name FIELD FORMAT 'FORMAT' INVALID
    The specified field format (at the specified column) is invalid. Valid field formats are AQ, BI, CH, FI, ZD, and PD.
  • SORT108E job-number job-name SEQUENCE 'SEQUENCE' INVALID
    The sequence operand (at the specified column) must be A or D for ascending or descending sequences respectively.
  • SORT109E job-number job-name TOO MANY FIELDS SPECIFIED
    Control fields are limited to 16.
  • SORT110E job-number job-name NON-NUMERIC DATA DETECTED
    Numeric data is expected at the specified column.
  • SORT111E job-number job-name 'OPERATOR' OPERATOR ALREADY PROCESSED
    The specified operator (at the specified column) has already been processed.
  • SORT112E job-number job-name 'EXIT'' EXIT NOT SUPPORTED
    The specified exit (at the specified column) is not supported. Only the E15 and E35 exits are supported by MFJSORT.
  • SORT114E job-number job-name EXPECTED '(' NOT FOUND
    A left parenthesis is expected at the specified column but has not been found.
  • SORT115E job-number job-name BOOLEAN OPERATOR 'OPERATOR' INVALID
    The specified Boolean operator (at the specified column) is invalid. Valid Boolean operators are EQ, NE, LT, LE, GT, and GE.
  • SORT118E job-number job-name SORT / MERGE CONFLICT
    Both SORT and MERGE commands have been found; only one can be specified. The second command is at the specified column.
  • SORT119E job-number job-name INCLUDE / OMIT CONFLICT
    Both INCLUDE and OMIT commands have been found; only one can be specified. The second command is at the specified column.
  • SORT120E job-number job-name SORT STATEMENT MISSING FIELDS OPERAND
    The SORT command statement does not contain a FIELDS operand.
  • SORT121E job-number job-name MERGE STATEMENT MISSING FIELDS OPERAND
    The MERGE command statement does not contain a FIELDS operand.
  • SORT122E job-number job-name INCLUDE STATEMENT MISSING COND OPERAND
    The INCLUDE command statement does not contain a COND operand.
  • SORT123E job-number job-name OMIT STATEMENT MISSING COND OPERAND
    The OMIT command statement does not contain a COND operand.
  • SORT124E job-number job-name FIELD POSITION 'NUMBER' INVALID
    The specified field position is invalid. Field positions can start at 1 but must not exceed the length of the SORTIN record, allowing for the length of the control field.
  • SORT125E job-number job-name FIELD LENGTH 'NUMBER' INVALID
    The field length specified is too long. Control fields are limited to 1024 bytes in length. Byte(.bit) notation is not supported.
  • SORT126E job-number job-name RECORD LENGTH 'NUMBER'' INVALID
    The specified record length is invalid. Record lengths may not exceed 32768 bytes.
  • SORT127E job-number job-name MISSING SORT/MERGE/COPY COMMAND STATEMENT
    A SORT, MERGE, or COPY command statement is required.
  • SORT128E job-number job-title EXPECTED ')' NOT FOUND
    A closing parenthesis ')' was expected and not found.
  • SORT129E job-number job-name EXPECTED '=' NOT FOUND
    '=' was expected and not found.
  • SORT130E job-number job-name EXPECTED 'F' OR 'V' NOT FOUND
    Either F or V must be specified to indicate recording mode (non-emulation mode).
  • SORT131E job-number job-name EXPECTED 'IX', 'RL', 'SQ', OR 'LS' NOT FOUND
    Organization must be specified as either IX, RL, SQ or LS (non-emulation mode).
  • SORT132E job-number job-name PRIME KEY MUST BE SPECIFIED FIRST
    When specifying keys for a USE OR GIVE indexed file (non-emulation mode), the prime key must be specified first.
  • SORT133E job-number job-name EXPECTED 'P', 'AD', 'A', OR 'C' NOT FOUND
    Key type for a USE OR GIVE indexed file must be specified as one of P (primary), AD (alternate permitting duplicates) A (alternate not permitting duplicates) or C (component).
  • SORT134E job-number job-name KEYWORD/VALUE 'VALUE' INVALID FOR DFSORT EMULATION
    The specified keyword is not valid for DFSORT emulation.
  • SORT135E job-number job-name KEYWORD/VALUE 'VALUE' INVALID FOR SYNCSORT EMULATION
    The specified keyword is not valid for SYNCSORT emulation.
  • SORT136E job-number job-name NO GIVE FILE SPECIFIED FOR OUTFIL GROUP
    No GIVE file has been specified for the current OUTFIL group (non-emulation mode).
  • SORT137E job-number job-name NO USE FILE SPECIFIED
    No USE file has been specified for the SORT (non-emulation mode).
  • SORT138E job-number job-name TARGET LITERAL 'LITERAL' TOO LONG IN CHANGE
    The set-constant in a CHANGE statement must not be longer than the specified length of the output field to be inserted (v).
  • SORT139E job-number job-name SUBSTRING COMPARISON MUST BE WITH CHARACTER LITERAL
    The right-hand side of a substring comparison must be a character literal.
  • SORT140E job-number job-name INVALID BINARY DIGIT DETECTED
    An invalid digit has been found in a binary literal. Valid digits are 0 and 1.
  • SORT141E job-number job-name CANNOT SPECIFY SAVE WITH EITHER INCLUDE OR OMIT
    Only one of INCLUDE, OMIT or SAVE may be specified for any OUTFIL group.
  • SORT142E job-number job-name REPEATED FILES= OR FNAMES=
    Only one of FILES= or FNAMES= may be specified for any OUTFIL group.
  • SORT191I job-number job-name OPERATOR 'OPERATOR' IGNORED
    The specified operator (at the specified column) is not supported and has been ignored. Processing continues without error.
  • SORT192I job-number job-name OPERAND 'OPERAND' IGNORED
    The specified operand (at the specified column) is not supported and has been ignored. Processing continues without error.
  • SORT193E job-number job-name INVALID HEX DIGIT DETECTED
    An hexadecimal digit (0 - 9 or A - F) is expected at the specified column but has not been found.
  • SORT194I job-number job-name NO ALTSEQ COMMAND SPECIFIED FOR 'AQ' SORT FIELD FORMATS; 'CH' ASSUMED
    A SORT control field requests an alternate collating sequence but no ALTSEQ command statement is specified. The standard collating sequence has been used instead. Processing continues without error.
  • SORT195I job-number job-name SORTWORK DIRECTORY 'DIRECTORY' IS INVALID; USING CURRENT DIRECTORY
    The MFJWORK or TEMP environment variable does not contain a valid device or directory path. The current directory has been used for temporary files instead. Processing continues without error.
  • SORT196E job-number job-name SUM / COPY CONFLICT
    The SUM command (at the specified column) cannot be used when the FIELDS=COPY statement is in effect.
  • SORT197E job-number job-name INREC / MERGE CONFLICT
    The INREC command (at the specified column) cannot be used with MERGE operations.
  • SORT198E job-number job-name NON-NUMERIC DATA DETECTED IN 'ZD' SUM FIELD
    Non-numeric data has been found in a field specified as zoned decimal.
  • SORT199E job-number job-name TOO MANY OUTFIL STMTS OR TOO MANY FIELDS ON OUTFIL STMT(S)
    More than 16 SORTOFnn files are specified by the OUTFIL command(s).
Parent topic: SORT - MFJSORT Error Messages


Generate SPD File tool

The Generate SPD File tool enables you to generate stored procedure definition (SPD) files from extracted DB2 schema. You can use a generated SPD file to generate a COBOL wrapper.

The Generate SPD File tool provides the following functionality:
  • Enables you to select one or more stored procedures from a Schema Extract file.
  • Generates selected stored procedures into a stored procedure definition file.
  • If HCOSS is opened from within the IDE and a SQL Server Database project is open in , the Generate SPD File tool can also generate a COBOL wrapper program that executes the stored procedures in the SPD file, and include both the SPD file and the generated program in the current project.
  • If any selected stored procedure contains a TIMESTAMP or DATE parameter, the Generate SPD File tool changes it to DATETIME2 and SMALLDATETIME respectively generates a post-deployment script file that alters the stored procedure after successful deployment to ensure compatibility between Java and SQL Server. However, if your application interfaces only with other COBOL applications, you have the option to edit the generated SPD file and change DATETIME2 back to TIMESTAMP and SMALLDATETIME back to DATE.
    Note: If your project was created using the SQL Server Database Project template, and one or more of your selected stored procedures contains a DATETIME2 or SMALLDATETIME parameter, you must add the post-deployment script to the project manually before running the Generate SPD File tool.
Related tasks
To generate a stored procedure definition (SPD) file
Related reference
Generate SPD File tab


SQL Server RM Switch Module

Provides the information required to build the SQL Server RM switch module.

The SQL Server module provides two-phase commit support using the Microsoft Distributed Transaction Server (MS DTC), and ensures that any database connections made using this switch module all participate in a single XA transaction. MSDTC must be running on both the client machine, and also the machine(s) where SQL Server is hosted.

Source Code
The SQL Server RM switch module COBOL source file, ESMSSQL.CBL is located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\xa directory.
Build Requirements
To build the SQL Server RM switch module, you must have the Windows Software Development Kit (SDK) installed for your version of Windows.

Some OpenESQL directives are process-based, and typically need to be set in within the code of the program that makes the database connection.

Before building this switch module, ensure that your LIB environment variable contains the path to your Windows SDK LIB directory.

If you are executing services under Enterprise Server that are deployed as container-managed applications, the applicable directives must be specified when compiling the RM switch module, rather than when compiling your program source. For more information, see the list of Process-based OpenESQL directives in the topic Scope - OpenESQL SQL Compiler Directive Options.

Building the Switch Module
Method 1
  1. Start an Enterprise Developer command prompt, 32-bit or 64-bit depending on the application, running as an administrator.
  2. Change to the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\xa directory (default location).
  3. Enter build mssql [directives]
Method 2
  1. Start an Enterprise Developer command prompt, 32-bit or 64-bit depending on the application.
  2. Copy all files from the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\xa directory (default location) to any location where you have WRITE permission.
  3. Change to the directory containing the copied files.
  4. Enter build mssql [directives]
Build Output
The build process produces two binary switch module files from the ESMSSQL.CBL COBOL source file:
Binary File | Type
ESSQLXA.DLL | static
ESSQLXA_D.DLL | dynamic

You can register an RM switch module with Enterprise Server dynamically, or register it statically depending on which binary file you use. We recommend that you use the dynamic switch module option, as this ensures that only active databases used in the global transaction participate in the TM/RM XA flow.

Additional Resources
For more information on using the SQL Server RM switch module, including the xa_open string definition and MSDTC details, see SQL Server xa_open string.
Related concepts
SQL xa_open string Configuration Options


JCLCM0126E %1$s is not yet supported.

Parent topic: JCLCM0000 - JCLCM0199


MAX_POOL_THREAD_CASTRC

Sets the maximum number of pool threads for CASTRC.
Restriction: You only need to use this variable when recommended by Micro Focus SupportLine.

Valid values are 2-512. If a variable is not set, the default value for that process is used. If a variable is set, then a console message is emitted at process startup to indicate that the value has been modified.

Parent topic: Reserved Environment Variables


JCLCM0487E Global output limit number for limitation type too long

The value of the limitation is too large. Valid values are
PAGES | 0-99999999
LINES | 0-99999999
BYTES | 0-999999
CARDS | 0-99999999
OUTLIM | 1-16777215

Resolution:

Correct the value to be within the range.

Parent topic: JCLCM0400 - JCLCM0499


JCLAM0239I Dataset attribute attribute-name unchanged

The attribute was not changed because it is the same as the existing setting.

Resolution:

No action is required.

Parent topic: JCLAM0231 -


MAX_POOL_THREAD_CASGATE

Sets the maximum number of pool threads for CASGATE.
Restriction: You only need to use this variable when recommended by Micro Focus SupportLine.

Valid values are 2-512. If a variable is not set, the default value for that process is used. If a variable is set, then a console message is emitted at process startup to indicate that the value has been modified.

Parent topic: Reserved Environment Variables


JCLCM0123S Expired password caused SAF failure on the host.

Parent topic: JCLCM0000 - JCLCM0199


JCLAM0225E Insufficient authority to alter/change dataset %

Lack of permissions to perform this action.

Resolution:

Contact your system administrator.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0006S <name> data set/member is unsuitable or does not exist

Resolution:

Make sure that the INF dataset/member specified in the REPRO command already exists.

A new Dynamic PDS member, when used as INF in a REPRO command, becomes unsuitable if it has not been updated before the REPRO command processing. In the case of dynamic PDS members, a reference to a non-existing member in the JCL leads to the creation of an empty member, and at the end of the job step, it will be deleted if it has not been opened for output/extend/update.

Parent topic: JCLAM0000 - JCLAM0119


Filter the Data File

  1. In the Navigation group, click [image] (Filter).

    The Filter dialog box appears.

    Filters are constructed by adding one or more conditions.

  2. Click New Ref.

    The basic reference elements appear.

  3. In the Field fields, enter 10 as the start position, and 3 as the number of positions on from that in which to filter within each record.

  4. Ensure the Operator field is set to =.
  5. In the Value field, enter "mr ".
    Note: Ensure that you include the space shown at the end of the string.
  6. Click New Field.

    The basic field elements appear.

    Note: The New Field option is only available when a structure file has been applied to the data file.
  7. Click [image] to the right of EM-POSITION and select MN-AGE.
  8. Change the Operator field to <.
  9. In the Value field, enter 40.
  10. Ensure Match All is selected.

    This means that only records that match both criteria are displayed.

  11. Click Filter.

    The results filter on the records for all males that are managers under 40 years of age:

  12. To display all records again, click [image] in the Records group and select All.

    The entire data file appears.

Related reference
Filter Operators
Filtering a Data File


MAX_POOL_THREAD_CASDBC

Sets the maximum number of pool threads for CASDBC.
Restriction: You only need to use this variable when recommended by Micro Focus SupportLine.

Valid values are 2-512. If a variable is not set, the default value for that process is used. If a variable is set, then a console message is emitted at process startup to indicate that the value has been modified.

Parent topic: Reserved Environment Variables


Results tab

Error Details (double-click to view SQL in context) grid

A file-by-file summary of errors found during the assessment or code conversion processes.

File Path
The paths to and filenames of source files listed in the column.
Line Num
Line number in the program where the SQL statement is found.
Error Type
The type of SQL error generated for the statement.
Error Message
The error returned for the original DB2 SQL statement.
HCOSS Message
The message returned for the SQL statement after HCOSS conversion.
DB2 SQL
The source code of the original DB2 SQL statement.
File Path
The path to and filename of the source file selected on the grid.
Line
The line number in the program where the SQL statement is found in the selected source file.
Error Type
The type of SQL error generated for the statement for the selected source file.
Error Message
The error returned for the original DB2 SQL statement found in the selected source file.
HCOSS Message
The message returned for the SQL statement after HCOSS conversion of the selected source file.
DB2 SQL
The source code of the original DB2 SQL statement found in the selected source file.
Related concepts
Assess Application Migration Tool
Related tasks
To assess application migration


JCLCM0013S Job cancelled by global OUTLIM setting of setting

The job has been cancelled because the global OUTLIM value has been exceeded.

Resolution:

None.

Parent topic: JCLCM0000 - JCLCM0199


JCLUT0011E "keyword" is not compatible with a preceding keyword

Message

"%1$s" is not compatible with a preceding keyword.

Where %1$s is a keyword or command.

Message Information

The command or keyword cannot be used with one of the others on the same EXEC card.

Resolution

Check the combination of keywords.

Parent topic: JCLUT Error Messages


JCLAM0231E Unable to acquire exclusive lock on dataset "dataset-name"

The action requires an exclusive lock on the named dataset but was unable to obtain it.

Resolution:

Ensure the dataset is not locked by another step, job or process.

Parent topic: JCLAM0231 -


JCLAM0120 - JCLAM0139

  • JCLAM0120S job-number job-name UNKNOWN COMMAND [COMMAND]
    The specified command is not known to MFJAMS.
  • JCLAM0121E job-number job-name GDG IS NOT EMPTY [GDGNAME]
    A DELETE command has been attempted for a generation data group which still contains cataloged entries.
  • JCLAM0122I job-number job-name HOST ENTRY RETAINED [ENTRYNAME]
    The specified entryname, which resides on the host, has been retained (not deleted).
  • JCLAM0123S job-number job-name GDG LIMIT MISSING OR ZERO
    An attempt to define a new GDG must specify the number of entries to maintain before automatic deletion.
  • JCLAM0124I job-number job-name GDG LIMIT CHANGED TO 31
    You have requested more than the maximum number of GDG entries allowed.
  • JCLAM0125S job-number job-name RELATENAME NOT CATALOGED [ENTRYNAME]
    The dataset specified by RELATENAME must exist before an alternate index can be defined.
  • JCLAM0126S job-number job-name FILE MISSING OR INVALID TYPE [FILENAME]
    The specified workstation file cannot be located.
  • JCLAM0127I job-number job-name ALTERNATE INDEX DEFINED [ENTRYNAME]
    The alternate index has been defined. The appropriate workstation file has been updated to reflect the new index keys.
  • JCLAM0128I job-number job-nameNUMBER RECORDS INDEXED
    The keys for the specified number of records have been added for the newly-defined alternate index.
  • JCLAM0129S job-number job-name INVALID PRIMARY KEY OR RECORDSIZE
    The key position plus the key length exceeds the defined record length.
  • JCLAM0130S job-number job-name DD MISSING [DDNAME]
    A DD statement for the specified DD name is not defined in your JCL.
  • JCLAM0131S job-number job-name INSUFFICIENT DCB [DATASETNAME]
    The specified dataset does not have complete data control block characteristics.
  • JCLAM0132S job-number job-name I/O ERROR [DATASETNAME]
  • JCLAM0133S job-number job-name I/O STATUS [FILE STATUS]
  • JCLAM0134I job-number job-namenumber Records processed
    The specified number of records have been processed.
  • JCLAM0135I job-number job-namenumber Datasets listed
    The specified number of data sets have been listed by the LISTCAT command.
  • JCLAM0136W job-number job-name PARM IGNORED FOR SEQ DATASETS [PARAMETER]
    The specified parameter is invalid for sequential datasets.
  • JCLAM0137I job-number job-name DATASET VERIFIED [DATASETNAME]
    The specified dataset has been verified. The dataset was opened and closed successfully.
  • JCLAM0138I job-number job-name DATASET VERIFIED(LOCKED) [DATASETNAME]
    The specified dataset has been verified even though the dataset is currently locked by another process.
  • JCLAM0139S job-number job-name DATASET MUST BE VSAM [DATASETNAME]
    The dataset name specified in the VERIFY command is not a VSAM dataset. Only VSAM datasets can be verified.
Parent topic: JCLAM Error Messages


JCLCM0489E No value decoded for limitation type global output limit

Syntax error in the environment setting for a limitation.

Resolution:

Correct the syntax error.

Parent topic: JCLCM0400 - JCLCM0499


JCLAM0223S Insufficient authority to update dataset %

Lack of permissions to perform this action.

Resolution:

Contact your system administrator.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0230S Insufficient authority to use PCDSN dataset %

Lack of permissions to perform this action.

Resolution:

Contact your system administrator.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0226U Insufficient authority for SYSPRINT dataset %

Lack of permissions to perform this action.

Resolution:

Contact your system administrator.

Parent topic: JCLAM0180 - JCLAM0230


Starting Compare and Synchronization Monitor from the user interface

From the IDE:

The MFA Compare and Synchronization Monitor main screen appears.

Related concepts
Mainframe Connections


JCLAM0236E Duplicate record "record number"

A duplicate record error has been generated.

Resolution:

No action is required.

Parent topic: JCLAM0231 -


JCLCM0491E Invalid action parameter for limitation type global SYSOUT limit

The action parameter is not one of the recognised options WARNING, CANCEL, or DUMP.

Resolution:

Correct the action parameter.

Parent topic: JCLCM0400 - JCLCM0499


To analyze schema extract data

  1. Use the Extract Schema tool to create one or more schema extract files.
  2. Start the HCOSS Assess Application Migration tool, and click the Data Analysis tab.
  3. Choose one of the following to apply to the Select Schema Extract File drop-down list:
    Local | To save the generated data analysis file to the directory specified by the Local HCOSS Directory HCOSS option.
    Shared | To save the generated data analysis file to the directory specified by the Shared HCOSS Directory HCOSS option.
  4. Select a schema extract file from the drop-down list.
  5. Click Analyze Schema Extract.

    Output appears in the output window on the lower part of the page.

  6. Repeat steps 4 and 5 to analyze additional schema. Output for each subsequent schema analysis is appended to the bottom of the output window. (Optional)
  7. To save the output to a file, click Save to File. (Optional)
  8. To close the current schema extract file and clear the output window, click Close Schema Extract. (Optional)
Related concepts
Why You Should Use the Assess Application Migration Tool
Related reference
Data Analysis tab


JCLAM0187I Dataset dsname is still allocated to (at least) ...

Dataset dsname is still allocated to (at least) one or more DDnames.

This message works in conjunction with JCLAM0188I: DD DDNAME. This may cause unexpected results later. These appear when a delete is performed on a dataset that is defined on a DD card and may be required by other actions in that step.

Resolution:

No action is required.

Parent topic: JCLAM0180 - JCLAM0230


MAX_POOL_THREAD_CASTMC

Sets the maximum number of pool threads for CASTMC.
Restriction: You only need to use this variable when recommended by Micro Focus SupportLine.

Valid values are 2-512. If a variable is not set, the default value for that process is used. If a variable is set, then a console message is emitted at process startup to indicate that the value has been modified.

Parent topic: Reserved Environment Variables


Synchronization rules

Data Set Name | The name of the data set being synchronized
Type | The type of data set being synchronized
Sync Mode One of:
  • BOTH - changes on either the mainframe or the workstation are synchronized
  • UPLOAD - only changes on the workstation are synchronized to the mainframe
  • DOWNLOAD - only changes on the mainframe are synchronized to the workstation
  • MONITOR - mimics the BOTH setting without changes being made
Advanced Set the following options:
  • Delete workstation file if mainframe member is deleted - during synchronization, if a member has been deleted on the mainframe, it will also be deleted on the workstation.
  • Delete workstation folder if library is deleted - during synchronization, if a library has been deleted on the mainframe, the workstation folder is also deleted if it contains no other synchronized members.
  • Handle embedded hex in MF MDECONV format - uses the MDECONV technique to deal with embedded hex values, that is, all translated hex values less than x'1f' have a null character inserted before the hex value, and the COBOL run-time system handles these embedded hex values.
  • Suppress embedded hex warning messages - pop-up messages when a non-printing character is received from the mainframe are not displayed; an entry is recorded in the log file instead.
Filters | Add a simple or advanced filter to the rule.
Binary Data Transfer | Transfer the data in binary format. Only available with PDS data sets.
Member Type | Specify the type of member in an Endevor, Panvalet or Librarian container,
Directory | The workstation directory used during synchronization
File Extension | The file extension to append to each member synchronized
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Compare and Synchronize Monitor


JCLCM0012S Job cancelled by user exit MFJUSOXT

The user exit has requested that the job be cancelled as the OUTLIM value has been exceeded.

Resolution:

None.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0490E Error parsing numeric value for limitation type global SYSOUT limit

The value for the limitation could not be converted to a numeric value.

Resolution:

Correct the setting to be a numeric value within the limitation range

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0486E Duplicate comma in action section of limitation type global SYSOUT limit

There is a syntax error in the environment settings for a limitation.

Resolution:

Fix the syntax error.

Parent topic: JCLCM0400 - JCLCM0499


JCLAM0000 - JCLAM0119

  • JCLAM0000I job-number job-name Interactive AMS Terminated
    The MFJAMS utility has terminated.
  • JCLAM0001I job-number job-name Number of hex digits should be even
    There must be an even number of digits in a hexadecimal string. A leading x"0" has been assumed.
  • JCLAM0002S job-number job-name Invalid hex. Digits must be 0 thru 9 or A thru F.
    An invalid hexadecimal character has been encountered. The character is not a digit (0 through 9) or a letter A through F.
  • JCLAM0003U job-number job-name MISSING SYSIN DD
    The jobstream does not contain the required SYSIN DD statement.
  • JCLAM0004U job-number job-name MISSING SYSPRINT DD
    The jobstream does not contain the required SYSPRINT DD statement.
  • JCLAM0006S <name> data set/member is unsuitable or does not exist
  • JCLAM0101S job-number job-name OPERAND TOO LONG [OPERAND]
    The specified operand is too long.
  • JCLAM0102S job-number job-name NUMERIC OPERAND REQUIRED [DATA]
    Numeric data was expected but the specified non-numeric data was received.
  • JCLAM0103S job-number job-name UNKNOWN PARAMETER [PARAMETER]
    The parameter is ignored, the return code is set to 12, and processing continues.
  • JCLAM0104S job-number job-name EXPECTED CONTINUATION NOT RECEIVED
    Continuation from the previous command statement was expected but not received.
  • JCLAM0105S job-number job-name INVALID ENTRYNAME FORMAT [ENTRYNAME]
    The specified entry name does not conform to the rules for MVS dataset naming.
  • JCLAM0106S job-number job-name REQUIRED OPERAND MISSING [OPERAND]
    The specified operand was expected but not received.
  • JCLAM0107S job-number job-name INVALID COMMAND (PARENS) [COMMAND]
    Command statement syntax error.
  • JCLAM0108S job-number job-name INCOMPLETE COMMAND [COMMAND]
    Command statement syntax error.
  • JCLAM0109S job-number job-name NO ENTRYNAME SPECIFIED
    The command requires an entry name.
  • JCLAM0110E job-number job-name ENTRYNAME ALREADY EXISTS [ENTRYNAME]
    A DEFINE command has been specified for a dataset which already exists.
  • JCLAM0111I job-number job-name ENTRYNAME RENAMED TO [ENTRYNAME]
    The entryname has been renamed to the specified name.
  • JCLAM0112S job-number job-name UNABLE TO CATALOG [ENTRYNAME]
    MFJAMS is unable to catalog the specified entry name.
  • JCLAM0113I job-number job-name ENTRYNAME DEFINED [ENTRYNAME]
    The specified entry name has been defined and cataloged. The appropriate workstation files have been created.
  • JCLAM0114I job-number job-name ENTRYNAME DELETED [ENTRYNAME]
    The specified entry name has been deleted and removed from the catalog. The appropriate workstation files have been deleted.
  • JCLAM0115E 00000000000000job-numberjob-name ENTRYNAME NOT CATALOGED [ENTRYNAME]
    The specified entry name does not exist.
  • JCLAM0116S UNEXPECTED RETURN CODE FROM MVSCATIO [return-code]
    An internal error has been detected by MVSCATIO.
  • JCLAM0117S job-number job-name TOO MANY ENTRYNAMES SPECIFIED
    The DELETE command is limited to 99 entry names.
  • JCLAM0118S job-number job-name PARAMETER NOT SUPPORTED [PARAMETER]
    The parameter is not supported by MFJAMS or is invalid for the type of dataset being defined.
  • JCLAM0119S job-number job-name MODELNAME NOT CATALOGED [ENTRYNAME]
    The specified entry name used as a model name does not exist.
Parent topic: JCLAM Error Messages


JCLUT0006E

Message

SYSUT1 = SYSUT2 nothing to do

Message Information

SYSUT1 and SYSUT2 reference the same file

Parent topic: JCLUT Error Messages


SORT200 - SORT399

  • SORT205I: job-number job-name INPUT file 'ddname'
    Informational message showing the name of the input file for the SORT operation just performed.
  • SORT206I: job-number job-name OUTPUT file 'ddname'
    Informational message showing the name of the output file for the SORT operation just performed.
  • SORT207I: job-number job-name OUTFIL file 'ddname '
    Informational message showing the name of the output file for the SORT operation just performed.
  • SORT301E: job-number job-name Position/Length bit specification ' byte.bit' must be >= 0 and <= 7.
    The bit portion of the byte.bit position or length specification must be between 0 and 7.
  • SORT399I: job-number job-name End of Micro Focus MFJSORT Utility.
    Informational message indicating the end of the SORT process.
Parent topic: SORT - MFJSORT Error Messages


Enter the required information

Specify the name of the Panvalet user code on which to filter the data set.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Data Analysis tab

Select Schema Extract File
Lists schema extract files from which to choose.
Local
Sets the Assess Application Migration tool to look for schema extract files in and save output files to the directory specified by the Local HCOSS Directory HCOSS option.
Shared
Sets the Assess Application Migration tool to look for schema extract files in and save output files to the directory specified by the Shared HCOSS Directory HCOSS option.
Analyze Schema Extract
Analyze the schema selected from the Select Schema Extract File list.
Close Schema Extract
Closes the current schema extract file and clears the output window.
Save to File
Save the contents of the output window to a file.
Related concepts
Why You Should Use the Assess Application Migration Tool
Related tasks
To analyze schema extract data


Rename Catalog File

Enter the new name for the data set or item.
Note: The new name is only used when displaying the catalog in Server Explorer. The file or directory name on disk is not renamed.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
The Local Catalog


MAX_POOL_THREAD_CASTSC

Sets the maximum number of pool threads for CASTSC.
Restriction: You only need to use this variable when recommended by Micro Focus SupportLine.

Valid values are 2-512. If a variable is not set, the default value for that process is used. If a variable is set, then a console message is emitted at process startup to indicate that the value has been modified.

Parent topic: Reserved Environment Variables


JCLUT0108S

Message

MFDG internal error (%1$s)

Where %1$s is subcode

Message Information

An error occurred in the MFDG program. The error code indicates the position. These errors are related to temporary file access or memory assignment.

Subcodes:

  • 002 - Open output DATAFL
  • 003 - Write DATAFL
  • 004 - Create temp file
  • 005 - Temp file count > max allowed
  • 006 - Allocate FD-REC
  • 007 - Allocate CREATE-REC
  • 008 - Allocate REPEAT-REC
  • 009 - Open input DATAFL
  • 010 - Allocate CREATE-NAME
  • 011 - Allocate DSD

Resolution

Check that disk space and swap space is available for temporary files and memory allocation. If the problem persists contact Micro Focus SupportLine.

Parent topic: JCLUT Error Messages


JCLCM0127S Host dataset %1$s unexpectedly created by alien job.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0124S Invalid user id caused SAF failure on the host.

Parent topic: JCLCM0000 - JCLCM0199


JCLUT0107S

Message

Incompatible DCB properties

Message Information

The concatenated data in SYSUT1 have different LRECL values.

Resolution

The data with the largest LRECL value must appear first on the list of concatenated data in SYSUT1.

Parent topic: JCLUT Error Messages


JCLUT0008E

Message

Missing or empty INPUT DD(%1$s).

Where %1$s is Dataset Name.

Message Information

The INPUT file could not be found in the catalog or is empty.

Resolution

The INPUT file must exist, be cataloged and contain at least one record.

Parent topic: JCLUT Error Messages


Assessment Tasks tab

Assessment Properties group

Available Assessments
List of previously created assessment tasks.
SQL Server Connection
The name of an existing SQL Server connection.
Qualifier (default schema)
The name of a schema to use as the default qualifier for this assessment. Optional.
Ignore Schema Errors
When checked, errors related to schema specification and HCOSS table and function names are ignored and not reported in the results. Default is checked.
Note: Do not uncheck this checkbox if you have not installed HCOSS on the server machine that contains your SQL Server database.
Source Code Path
The directory containing your COBOL source files or the parent directory to one or more subdirectories containing your COBOL source files. Use the browse button to select a directory.
New
Create a new assessment task.
Save
Save the assessment task specified in the Available Tasks field.
Delete
Delete the assessment task specified in the Available Tasks field.

File Counts group

Total
Total number of files available for assessment.
NoSQL
Total number of files that contain no SQL code.
Processed
Total number of files that have completed processing.
Pending
Number of files awaiting processing.

Statement Counts group

Total SQL Statements
The total number of DB2 SQL statements encountered in the processed files.
OK
For each of the As is, Code convert, HCOSS no BIND, and HCOSS with BIND conversion scenarios, reports the number of DB2 SQL statements that can be executed successfully in SQL Server.
Must fix
For each of the As is, Code convert, HCOSS no BIND and HCOSS with BIND conversion scenarios, reports the number of DB2 SQL statements that require a manual fix before they can execute successfully in SQL Server.
In doubt
For each of the As is, Code convert, HCOSS no BIND and HCOSS with BIND conversion scenarios, reports the number of DB2 SQL statements for which HCOSS cannot determine the potential for successful execution in SQL Server.
As is
Reports the number of DB2 SQL statements that fall into each of the OK, Must fix, and In doubt categories if you were to use the code in its original state.
Code convert
Reports the number of DB2 SQL statements that fall into each of the OK, Must fix, and In doubt categories if you were to manually convert your SQL DB2 statements to T-SQL statements before migrating to SQL Server.
HCOSS no BIND
Reports the number of DB2 SQL statements that fall into each of the OK, Must fix, and In doubt categories if you were to use the code in its original state and compile your SQL Server application in Enterprise Developerusing the SQL(DIALECT) directive option without the SQL(DBRMLIB) directive option.
HCOSS with BIND
Reports the number of DB2 SQL statements that fall into each of the OK, Must fix, and In doubt categories if you were to use the code in its original state and compile your SQL Server application in Enterprise Developerusing both the SQL(DIALECT) and SQL(DBRMLIB) directive options. For more information, see the Manage Packages and Plans Tool and DSN BIND utility topics.

Summary grid

A file-by-file summary of the assessment, including a breakdown of the In doubt and Must fix counts represented in the Statement Counts group.

Assessment Actions group

Process Files
Run the assessment process.
Pause
Pause assessment processing.
Reset Status
After processing completes, clear all fields in preparation for rerunning the current assessment or for running a new assessment.
Export Report (txt)
Save the assessment specifications and results as a text file.
Export Details (csv)
Export the information in the Summary grid on the Results tab to a CSV file compatible with spreadsheet software.
Related concepts
Manage Packages and Plans Tool
Binding Applications
DSN Bind Utility


JCLCM0121S Unexpected return type from RJSECA-FC-Execute %1$s.

Parent topic: JCLCM0000 - JCLCM0199


MAX_POOL_THREAD_CASMQB

Sets the maximum number of pool threads for CASMQB.
Restriction: You only need to use this variable when recommended by Micro Focus SupportLine.

Valid values are 2-512. If a variable is not set, the default value for that process is used. If a variable is set, then a console message is emitted at process startup to indicate that the value has been modified.

Parent topic: Reserved Environment Variables


JCLUT0009E

Message

INPUT DD(%1$s) on CREATE or FD CARD is not on DSD CARD.

Where %1$s is Dataset name

Message Information

The INPUT dataset specified is not mentioned in the DSD INPUT parameter.

Resolution

Include the dataset name in the INPUT parameters of the DSD statement.

Parent topic: JCLUT Error Messages


JCLAM0221S Insufficient authority to define new dataset %

Lack of permissions to perform this action.

Resolution:

Contact your system administrator.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0188I DD DDNAME. This may cause unexpected results later.

Emitted in conjunction with JCLAM0187I and reports on a DDNAME that still has a dataset name allocated to it.
This message works in conjunction with JCLAM0187I: Dataset dsname is still allocated to (at least) ... These appear when a delete is performed on a dataset that is defined on a DD card and may be required by other actions in that step.

Resolution

No action is required.

Parent topic: JCLAM0180 - JCLAM0230


Catalog Location

Enter the path and name of your catalog file (CATALOG.DAT).
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
The Local Catalog


Filtering catalog items

Specify a filter criteria with which to filter your local catalog, displaying only those items that match the filter. You can specify fully-qualified or partial names, or use an asterisk for additional matching possibilities.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
The Local Catalog


JCLAM0224E Insufficient authority to delete dataset %

Lack of permissions to perform this action.

Resolution:

Contact your system administrator.

Parent topic: JCLAM0180 - JCLAM0230


JCLCM0011I OUTLIM limit for DD name incremented by amount by user exit MFJUSOXT

The user exit has incremented the OUTLIM value by <amount>.

Resolution:

None.

Parent topic: JCLCM0000 - JCLCM0199


Synchronization filters

Select the type of filter to add to the rule:

Simple Filter Enter a simple filter
Note: Hover over the field for tips of the syntax you can use.
Advanced Filters
  1. Select Use Advanced Filters, then click Add Filters.

    The Add Advanced Filter dialog box appears.

  2. Choose the required filter, then select how it should filter:
    • Include to include matching items
    • Exclude to exclude matching items
  3. Click OK.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Compare and Synchronize Monitor


JCLAM0222S Insufficient authority to read dataset %

Lack of permissions to perform this action.

Resolution:

Contact your system administrator.

Parent topic: JCLAM0180 - JCLAM0230


Migration Scenarios

The Assess Application Migration tool runs a multi-phase process to determine the migration potential of each SQL statement contained in your original IBM z/OS mainframe DB2 SQL. The tool considers and reports on the following four scenarios for each source file containing DB2 EXEC SQL code:
  • As is - use existing DB2 SQL code as is.
  • Code convert - convert the DB2 SQL code to T-SQL code.
  • HCOSS no BIND - convert the DB2 SQL code using SQL(DIALECT) only.
  • HCOSS with BIND - convert the DB2 SQL code using both SQL(DIALECT) and SQL(DBRMLIB). For more information, see the Manage Packages and Plans Tool and DSN BIND utility topics.
For each scenario, the tool reports the total number of DB2 SQL statements that fall into these categories:
  • OK - statements that can be likely migrated to SQL Server without alteration
  • Must fix - statements that are not compatible with SQL Server and require a manual code change
  • In doubt - statements for which HCOSS cannot determine migration potential
Related concepts
Manage Packages and Plans Tool
DSN Bind Utility
Why You Should Use the Assess Application Migration Tool
Related tasks
To assess application migration
Related reference
DSN command


JCLCM0488E Closing bracket before action in limitation type global SYSOUT limit

The syntax of the environment setting is incorrect.

Resolution:

Correct the syntax error.

Parent topic: JCLCM0400 - JCLCM0499


SQL Compiler Directive Options - HCOSS

Important: When compiling from within , set these directives.
Related concepts
HCO for SQL Server Compiler Directive Options for PL/I


JCLUT0007E

Message

NAME, LENGTH or QUANTITY omitted.

Message information

Syntax Error. An IEBDG control statement is missing the NAME, LENGTH or QUANTITY value.

Solution

Correct the syntax and resubmit the job.

Parent topic: JCLUT Error Messages


Assess Application Migration Tool

The Assess Application Migration tool provides you with a blueprint for how prepare your source code for successful migration to SQL Server by reporting the errors you might encounter when DB2 EXEC SQL statements are executed on SQL Server. This is done by providing detailed information for several conversion scenarios. Before migrating your applications to SQL Server, we strongly recommend that you analyze your application's migration potential using this tool.

Related reference
Source Code tab
Results tab


To assess application migration

  1. From the HCOSS Assess Application Migration tool, click the Assessment Tasks tab.
  2. Do one of the following:
    • To define a new assessment task:
      1. Click New.
      2. In the Name field, type a name for the assessment task file.
      3. Click the browse button and navigate to the directory containing your COBOL source files, or the parent directory to one or more subdirectories containing your COBOL source files.
      4. Click OK.
    • To edit an existing assessment task, select an existing task from the Available Assessments drop-down list.
  3. From the SQL Server Connection drop-down list, select an existing SQL Server connection to use in the assessment.
  4. If you have a schema you want to use as the default qualifier for this assessment, type its name into the Qualifier (default schema) field. Optional.
  5. If you want HCOSS to report errors related to schema specification, uncheck Ignore Schema Errors. Optional.
    Note: Do not uncheck this checkbox if you have not created your SQL Server database.
  6. In the Summary grid's Check for SQL column, uncheck any files that you do not want to include in the assessment. If you want to select all of the files, right-click in the column, and then click Select All from the popup menu.
    Note:
    • To view the source for any file listed on the Summary grid, double-click the file name in the File Path column. This opens the Source Code tab. Use the Next EXEC SQL and Previous EXEC SQL buttons to move from one SQL statement to another.
    • The code that appears on the Source Code tab is the original source file if you have not processed the assessment. If you have, the code that appears is the converted code.
  7. Click Save to save the assessment task.
  8. Click Process Files.
  9. On the Results tab, review the assessment results.
  10. To see a comparison of the original source code along with converted source code, double-click a file listed on the Error Details grid, and view the code in the SQL Conversion tab.
Related concepts
Application Migration Process
Migration Scenarios
Related reference
Results tab
Source Code tab


JCLAM0160 - JCLAM0179

  • JCLAM0160S job-number job-name Secondary quantity invalid
    The secondary quantity is not a number.
  • JCLAM0161S job-number job-name "name" Dataset not found
    The named data set does not exist.
  • JCLAM0162S job-number job-name Mutually exclusive keywords specified
    Only one of these keywords is permitted.
  • JCLAM0163S job-number job-name The "*" specification must be surrounded by dots
    The * specification must be preceded and followed by a period.
  • JCLAM0164S Left parenthesis missing after "keyword"
  • JCLAM0165S Unrecognizable keyword "keyword"
    You have used a non-existent keyword, or one that is not supported.
  • JCLAM0166S A required keyword must follow "keyword"
    You have failed to use a keyword where it is required.
  • JCLAM0167S Command "%" is not supported
    The command is not implemented.
  • JCLAM0168S Invalid keyword value "value"
    The value is not of the required type or range.
  • JCLAM0169I The "command-name" command is not required. Command ignored
    This command is not needed in the Micro Focus environment.
  • JCLAM0170I Use host compatible form: "extension-name"
    You have used a Micro Focus JCL extension without a preceding %.
  • JCLAM0171S Password is not permitted here "level"
    LEVEL does not allow a password.
  • JCLAM0172S System Error. Insufficient space in vcat for token
    System error. token is a word or other token from the command, showing how far through processing the command the system had got when it ran out of space.
  • JCLAM0173I Excess VOLUME specification "%" ignored
  • JCLAM0174E keyword % in the DATA component is invalid
    You have used a keyword that does not exist, or is not allowed in this context, or is not supported.
  • JCLAM0175E keyword % in the INDEX component is invalid
    You have used a keyword that does not exist, or is not allowed in this context, or is not supported.
  • JCLAM0176I Data set dataset-name indexed
    Informational only.
  • JCLAM0177S Unexpected return-code return-code from CALLRB
    Indicates an internal error detected by CALLRB
  • JCLAM0178S Unexpected status-code status-code from CALLRB
    Indicates an internal error detected by CALLRB
  • JCLAM0179S Unable to obtain access to "dataset-name"
    System cannot obtain access to the specified dataset.
Parent topic: JCLAM Error Messages


JCLCM0010W SYSOUT Limit limit exceeded by DD name

One of the output limits has been exceeded.

Resolution:

None.

Parent topic: JCLCM0000 - JCLCM0199


JCLAM0189I(00) - Dataset attributes assumed to match PC file "pcFileName".

A new VSAM dataset has been allocated using the same name as that specified by pcFileName, which already exists. The IDCAMS allocation assumes that the new VSAM dataset has attributes that match the specified PC file.

Resolution:

No action is required.

Parent topic: JCLAM0180 - JCLAM0230


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.
Related information
CTF Trace File Formats
Example CTF Configuration Files


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 Enterprise Developer 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


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.
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).
Related information
CTF Trace File Formats
Example CTF Configuration Files


JCLAM0001I job-number job-name Number of hex digits should be even

There must be an even number of digits in a hexadecimal string. A leading x"0" has been assumed.

Resolution:

Add the missing hexadecimal digit in the appropriate position.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0002S job-number job-name Invalid hex. Digits must be 0 thru 9 or A thru F.

An invalid hexadecimal character has been encountered. The character is not a digit (0 through 9) or a letter A through F.

Resolution:

Correct the offending character(s).

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0003U job-number job-name MISSING SYSIN DD

The jobstream does not contain the required SYSIN DD statement.

Resolution:

Add a SYSIN DD statement to the jobstream to specify the location of your input utility control statements and try again.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0004U job-number job-name MISSING SYSPRINT DD

The jobstream does not contain the required SYSPRINT DD statement.

Resolution:

Add a SYSPRINT DD statement to the jobstream to specify the location where you want messages and other printed output to be written and try again.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0101S job-number job-name OPERAND TOO LONG [OPERAND]

The specified operand is too long.

Resolution:

Correct the operand and try again.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0102S job-number job-name NUMERIC OPERAND REQUIRED [DATA]

Numeric data was expected but the specified non-numeric data was received.

Resolution:

Correct the data and try again.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0103S job-number job-name UNKNOWN PARAMETER [PARAMETER]

The parameter is ignored, the return code is set to 12, and processing continues.

Resolution:

If appropriate, correct the parameter and try again.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0104S job-number job-name EXPECTED CONTINUATION NOT RECEIVED

Continuation from the previous command statement was expected but not received.

Resolution:

Check to make sure the previous record does not have an extraneous continuation character.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0105S job-number job-name INVALID ENTRYNAME FORMAT [ENTRYNAME]

The specified entry name does not conform to the rules for MVS dataset naming.

Resolution:

Correct the entry name and try again.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0106S job-number job-name REQUIRED OPERAND MISSING [OPERAND]

The specified operand was expected but not received.

Resolution:

Include the missing operand and try again.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0107S job-number job-name INVALID COMMAND (PARENS) [COMMAND]

Command statement syntax error.

An opening parenthesis "(" was expected but not received.

Resolution:

Correct the command and try again.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0108S job-number job-name INCOMPLETE COMMAND [COMMAND]

Command statement syntax error.

A closing parenthesis ")" was expected but not received.

Resolution:

Correct the command and try again.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0109S job-number job-name NO ENTRYNAME SPECIFIED

The command requires an entry name.

Resolution:

Correct the command to include an entry name and try again.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0110E job-number job-name ENTRYNAME ALREADY EXISTS [ENTRYNAME]

A DEFINE command has been specified for a dataset which already exists.

Resolution:

If appropriate, delete the dataset and try again.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0111I job-number job-name ENTRYNAME RENAMED TO [ENTRYNAME]

The entryname has been renamed to the specified name.

Resolution:

No action is required.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0112S job-number job-name UNABLE TO CATALOG [ENTRYNAME]

MFJAMS is unable to catalog the specified entry name.

Another user or process might be using the entry name or workstation file.

Resolution:

Try the operation again when the entry name or workstation file is available for exclusive use.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0113I job-number job-name ENTRYNAME DEFINED [ENTRYNAME]

The specified entry name has been defined and cataloged. The appropriate workstation files have been created.
Parent topic: JCLAM0000 - JCLAM0119


JCLAM0114I job-number job-name ENTRYNAME DELETED [ENTRYNAME]

The specified entry name has been deleted and removed from the catalog. The appropriate workstation files have been deleted.
Parent topic: JCLAM0000 - JCLAM0119


JCLAM0115E 00000000000000job-numberjob-name ENTRYNAME NOT CATALOGED [ENTRYNAME]

The specified entry name does not exist.

Resolution:

Correct the entry name or determine why it does not exist.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0117S job-number job-name TOO MANY ENTRYNAMES SPECIFIED

The DELETE command is limited to 99 entry names.

Resolution:

If you have provided a list of entry names, break the DELETE command into more than one command. If you have specified a generic entry name, specify a more restrictive generic entry name that does not result in more than 99 datasets.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0118S job-number job-name PARAMETER NOT SUPPORTED [PARAMETER]

The parameter is not supported by MFJAMS or is invalid for the type of dataset being defined.

This error occurs if you try to use unsupported features such as LSDS datasets, or if you try to define keys for an RRDS dataset.

Resolution:

Correct the parameter and try again.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0119S job-number job-name MODELNAME NOT CATALOGED [ENTRYNAME]

The specified entry name used as a model name does not exist.

The model name must exist in order to borrow characteristics from the model.

Resolution:

Correct the entry name or determine why it does not exist.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0120S job-number job-name UNKNOWN COMMAND [COMMAND]

The specified command is not known to MFJAMS.

Processing continues, however future commands might be affected by this error.

Resolution:

If appropriate, correct the command and try again.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0121E job-number job-name GDG IS NOT EMPTY [GDGNAME]

A DELETE command has been attempted for a generation data group which still contains cataloged entries.

Resolution:

Delete the cataloged GDG entries and try again, or specify the FORCE parameter to instruct MFJAMS to delete all GDG entries in addition to the GDG model.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0122I job-number job-name HOST ENTRY RETAINED [ENTRYNAME]

The specified entryname, which resides on the host, has been retained (not deleted).

Resolution:

No action is required.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0123S job-number job-name GDG LIMIT MISSING OR ZERO

An attempt to define a new GDG must specify the number of entries to maintain before automatic deletion.

Resolution

Specify the number of entries and try again.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0134I job-number job-namenumber Records processed

The specified number of records have been processed.

Resolution

No action is required.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0135I job-number job-namenumber Datasets listed

The specified number of data sets have been listed by the LISTCAT command.

Resolution:

No action is required.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0136W job-number job-name PARM IGNORED FOR SEQ DATASETS [PARAMETER]

The specified parameter is invalid for sequential datasets.

For example, you must not specify a FROMKEY for a sequential dataset.

Resolution

If appropriate, correct the parameter and try again.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0137I job-number job-name DATASET VERIFIED [DATASETNAME]

The specified dataset has been verified. The dataset was opened and closed successfully.

If the open failed, the index portion of the VSAM dataset has been recreated. The dataset is available for use.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0138I job-number job-name DATASET VERIFIED(LOCKED) [DATASETNAME]

The specified dataset has been verified even though the dataset is currently locked by another process.

The verify operation assumes that if another process has the dataset locked it is in satisfactory condition and can be successfully opened.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0139S job-number job-name DATASET MUST BE VSAM [DATASETNAME]

The dataset name specified in the VERIFY command is not a VSAM dataset. Only VSAM datasets can be verified.

Resolution

If appropriate, correct the dataset name and try again.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0140I job-number job-name LASTCC set to number

The condition code LASTCC has been set to the specified value.

Resolution:

No action is required.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0141I job-number job-name MAXCC set to number

The condition code MAXCC has been set to the specified value.

Resolution:

No action is required.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0142S job-number job-name AVERAGE RECORD LENGTH INVALID

The average record length must be greater than 0 bytes but not greater than 32760 bytes.

Resolution:

Correct the average record length and try again.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0143S job-number job-name MAXIMUM RECORD LENGTH INVALID

The maximum record length must be greater than 0 bytes but not greater than 32760 bytes.

Resolution:

Correct the maximum record length and try again.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0144S job-number job-name KEY LENGTH INVALID

The primary key length must be greater than 0 but not greater than 64.

Resolution:

Correct the primary key length and try again.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0145S job-number job-name KEY OFFSET INVALID

The key offset plus the key length exceeds the defined record length.

Resolution:

Correct the key offset and/or key length and try again.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0146E job-number job-nameNUMBER DUPLICATE KEYS

The specified number of duplicate keyed records have NOT been replaced by the REPRO command.

Resolution:

No action is required.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0147W job-number job-name 00000000 DATASETS LISTED

No datasets have been listed by the LISTCAT command.

Resolution:

No action is required.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0148E job-number job-name NO MATCHING ENTRIES [ENTRYNAME]

There are no entries in the catalog which match the pattern entry name specified for the delete request.

Resolution:

No action is required.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0151S job-number job-name Invalid dataclass name "name"

The specified data class name is not legal or is longer than 8 characters.

Resolution:

Correct the name and retry.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0152S job-number job-name Dataclass "name" does not exist

This specified data class has not been defined to this system.

Resolution:

Correct the name and retry, or define the data class with the specified name.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0153S job-number job-name UNEXPECTED MVSSMS FUNC_GU RETCODE [number]

Unexpected return code received from the MVSSMS (the data class manager).

Resolution:

Contact Micro Focus Support.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0154S job-number job-name THEN MUST FOLLOW AN IF COMMAND

The IF command must be followed by the THEN keyword.

Resolution:

Correct the command and retry.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0155I job-number job-name Remainder of command stream ignored

The remainder of the command stream has been ignored.

This is for one of the following reasons:

  • The CANCEL command has been executed
  • MAXCC has been set to 16

Resolution:

No action is required.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0156I job-number job-name CANCEL COMMAND EXECUTED

The CANCEL command has been executed.

Resolution:

No action is required.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0157S job-number job-name Space (CYL or TRK or REC) missing

Space, using one of the specified keywords, must be specified for a new data set.

Resolution:

Specify space parameters as appropriate and re-run.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0158S job-number job-name RECORG for input and output data set incompatible

Either the output file is RRDS and is not empty, or the input file is not RRDS.

Resolution:

Correct and re-run.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0159S job-number job-name Primary quantity invalid

The primary quantity is not a number.

Resolution:

Correct and re-run.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0160S job-number job-name Secondary quantity invalid

The secondary quantity is not a number.

Resolution:

Correct and re-run.

Parent topic: JCLAM0160 - JCLAM0179


JCLAM0161S job-number job-name "name" Dataset not found

The named data set does not exist.

Resolution:

Correct and re-run.

Parent topic: JCLAM0160 - JCLAM0179


JCLCM0163U job-number job-name MVSJOBNO ERROR ASSIGNING JOBNUM

An internal error has been detected while attempting to assign a job number. The return-code from MVSJOBNO.DLL is non-zero.

Resolution:

Contact SupportLine.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0170I job-number job-name JCL SCANNED - NO ERRORS

The job submitted contains no syntax errors.
Parent topic: JCLCM0000 - JCLCM0199


JCLCM0171E job-number job-name JCL SCANNED - JCL ERROR

The job submitted contains syntax errors which are detailed in other messages.

Resolution:

Use the job log in the spool view to resolve the JCL syntax errors.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0172E job-number job-name JOB FAILED - JCL ERROR

The job submitted contains a JCL syntax error.

Resolution:

Consult the JCL listing for the more details of the error.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0173I job-number job-name MFJUSCAN SCANNER EXIT - NO ERRORS

The JCL scanner user exit module MFJUSCAN was called and ended with a zero return code.
Parent topic: JCLCM0000 - JCLCM0199


JCLCM0174E job-number job-name MFJUSCAN SCANNER EXIT - JCL ERROR

The JCL scanner user exit module MFJUSCAN was called and ended with a non-zero return code.

Resolution:

Consult the JCL listing for additional information on the JCL errors detected by the user written MFJUSCAN user exit module.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0175S job-number job-name MFJUSCAN SCANNER EXIT - I/O ERROR ON FILENAME

An I/O error has occurred while attempting to process the user error file returned to the JCL scanner.

Resolution:

Ensure that the filename being returned by the user written MFJUSCAN user exit module is correct. Verify that the file has been properly formatted and that the file has been closed.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0181S job-number job-name JOB ABENDED - ERRORCODE

The job has ended abnormally with the specified return code.

Resolution:

Consult the JCL spool file listing for the exact reason for the failure.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0182I job-number job-name JOB ENDED - RC(RETURNCODE)

The job has ended normally with the specified return code.
Parent topic: JCLCM0000 - JCLCM0199


JCLCM0185U job-number job-name Job flushed upon User Exit request.

The user exit has requested that the job be flushed.
Parent topic: JCLCM0000 - JCLCM0199


JCLCM0187I job-number job-name JOB SUBMITTED JOBNAME

The specified job contains a valid job name, a job number has been assigned, and syntax checking of the JCL has started.
Parent topic: JCLCM0000 - JCLCM0199


JCLCM0188I job-number job-name JOB STARTED.

Execution of the submitted job has started.
Parent topic: JCLCM0000 - JCLCM0199


JCLCM0189I job-number job-name STEP BYPASSED STEPNAME.PROCSTEPNAME

Execution of the specified job step has been bypassed due to a prior abend or because of return codes.
Parent topic: JCLCM0000 - JCLCM0199


JCLCM0190I job-number job-name STEP STARTED STEPNAME.PROCSTEPNAME

Execution of the specified job step has started.
Parent topic: JCLCM0000 - JCLCM0199


JCLCM0191I job-number job-name STEP ENDED STEP1 - COND CODE CONDITION-CODE

Execution of the job step has completed normally with the specified return code.
Parent topic: JCLCM0000 - JCLCM0199


JCLCM0192S job-number job-name STEP ABENDED STEP01 - COND CODE ABEND-CODE

Execution of the job step has completed abnormally with the specified user abend, system abend, or run time error.

Resolution:

Correct the cause of the abnormal termination.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0193U job-number job-name PROGRAM NOT FOUND - PROGRAMNAME

The specified program cannot be located.

Resolution:

Correct the program name and/or correct your STEPLIB specifications to reflect the correct location of the program.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0194S job-number job-name DCB MODEL NOT FOUND - DDNAME

The specified DD statement references a DCB model data set which cannot be located.

Resolution:

Remove the reference to the DCB model on the DD statement or ensure that it exists as a valid entry in the catalog.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0195S job-number job-name DATASET IS NOT A GDG - DDNAME

The specified DD statement refers to a GDG data set with a bias (+1) or (-1), but no GDG model by the same name exists in the catalog.

Resolution:

Define the GDG model or correct the data set name on the DD statement to ensure that it refers to a valid data set name.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0197S job-number job-name DISP=MOD, DSN INCOMPATIBLE - DDNAME

The specified DD statement specifies DISP=MOD, which is incompatible with the organization of the data set name specified.

Resolution:

Correct the JCL error and resubmit the jobstream.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0200S job-number job-name DISP=NEW, DATASET EXISTS - DDNAME

The specified DD statement specifies DISP=NEW but the data set name specified already exists in the catalog.

Resolution:

Correct the JCL error and resubmit the jobstream.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0201S job-number job-name DATASET IS NOT A PDS - DDNAME

The specified DD statement refers to a PDS member but no PDS model by the same name exists in the catalog.

Resolution:

Define the PDS model or correct the data set name on the DD statement to ensure that it refers to a valid dataset name.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0202S job-number job-name DISP=OLD/SHR, DATASET NOT FOUND - DDNAME

The specified DD statement specifies DISP=OLD or DISP=SHR but the data set name specified does not exist in the catalog.

Resolution:

Correct the JCL error and resubmit the jobstream.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0402E job-number job-name MISSING EXECUTE STATEMENT

JCL error. At least one EXEC statement is required in the jobstream.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0403E job-number job-name TOO MANY PROCEDURES REFERENCED

JCL error. The job submitted has exceeded the maximum number of cataloged procedures that this system can load.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0404E job-number job-name MISSING PEND STATEMENT

JCL error. A PEND statement is required to end the instream procedure begun by a previous PROC statement.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0405E job-number job-name RECURSIVE, ILLEGAL NESTING, OR LIMIT EXCEEDED

JCL error. A procedure has attempted to execute another procedure. Nested procedures are not permitted.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0406E job-number job-name PROCEDURE NOT FOUND

JCL error. The procedure name specified cannot be located.

Resolution:

Check the procedure name and correct. Check the procedure libraries to be sure the specified procedure actually exists in the libraries accessible to the JCL scanner.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0407E job-number job-name INVALID LABEL

JCL error. The label on a JCL statement is invalid - for example, it exceeds eight characters.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0409E job-number job-name INVALID OPERATOR

JCL error. The JCL operator (EXEC, DD, etc.) contained on the statement is unknown.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0410E job-number job-name INVALID CONTINUATION

JCL error. The JCL statement contains an invalid continuation or the expected continuation was not received.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0411E job-number job-name OPERAND TOO LONG

JCL error. The JCL operand exceeds the length allowed for the JCL parameter.

For example, program names cannot exceed eight characters.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0412E job-number job-name NON-NUMERIC DATA DETECTED

JCL error. Non-numeric data has been found in an operand that is required to be numeric.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0413E job-number job-name DUPLICATE JOB

JCL error. More than one JOB statement has been detected.

Resolution:

Resubmit the JCL with only one job per jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0414E job-number job-name INVALID OR UNKNOWN OR UNEXPECTED OPERAND

JCL error. The operand received is not recognized.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0415E job-number job-name INVALID ADDRSPC OPERAND

JCL error. The ADDRSPC operand is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0416I job-number job-name INVALID JOBCLASS OPERAND IGNORED

JCL error. The JOBCLASS operand is improperly coded and has been ignored.

Resolution:

If necessary, correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0417I job-number job-name INVALID MSGCLASS OPERAND IGNORED

JCL error. The MSGCLASS operand on the JOB statement is improperly coded and has been ignored.

An appropriate default value will be used for jobstream execution.

Resolution:

If necessary, correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0418E job-number job-name INVALID MSGLEVEL OPERAND

JCL error. The MSGLEVEL operand is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0419E job-number job-name INVALID PERFORM OPERAND

JCL error. The PERFORM operand is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0420E job-number job-name INVALID PRTY OPERAND

JCL error. The PRTY operand is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0421E job-number job-name INVALID RD OPERAND

JCL error. The RD operand is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0422I job-number job-name INVALID REGION OPERAND IGNORED

JCL error. The REGION operand on the JOB or EXEC statement is improperly coded and has been ignored.

Resolution:

If necessary, correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0423E job-number job-name INVALID STEP NAME

JCL error. The job step name is invalid.

Resolution:

Make sure the name does not exceed eight characters. Make sure the name refers to a valid job step.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0424E job-number job-name INVALID PROCSTEP NAME

JCL error. The procedure step name is invalid.

Resolution

Make sure the name qualifiers do not each exceed eight characters. Make sure that specification of a procedure step name is valid where used.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0425E job-number job-name INVALID TIME OPERAND

JCL error. The TIME operand is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0426E job-number job-name INVALID TYPRUN OPERAND

JCL error. The TYPRUN operand is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0427E job-number job-name CONDITION STATEMENT IMPROPERLY FORMED

JCL error. The COND operand is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0428E job-number job-name INVALID CONDITION CODE

JCL error. The condition code is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0439E job-number job-name INVALID LABEL REFERENCE

JCL error. The label reference on a JCL statement is invalid.

Resolution:

Make sure the label reference is specified correctly, including stepname or procstepname as applicable.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0440E job-number job-name SYMBOL NOT FOUND

JCL error. The symbolic parameter cannot be found on the PROC or EXEC statement.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0441E job-number job-name UNKNOWN PROCSTEP NAME

JCL error. The procedure step name referenced has not been defined by a previous EXEC statement.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0442E job-number job-name INVALID OVERRIDE

JCL error. The override is invalid.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0443E job-number job-name INVALID POSITIONAL OPERAND

JCL error. The positional operand was not expected.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0444E job-number job-name INVALID DATASET NAME

JCL error. The data set name is invalid.

Resolution:

Check the data set name to make sure it follows the MVS data set naming rules.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0445E job-number job-name INVALID REFER BACK

JCL error. The refer back is invalid.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0446E job-number job-name DCBMODEL NAME NOT FOUND

JCL error. The model name specified in the DCB parameter cannot be found in the catalog.

Resolution:

You must catalog model names in the catalog with model DCB characteristics.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0447E job-number job-name INVALID DDNAME

JCL error. The DD name is invalid.

Resolution:

Make sure the DD name is no longer than eight characters.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0448E job-number job-name INVALID DDNAME REFERENCE

JCL error. The DD name deferral is invalid.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0449E job-number job-name MISMATCHED PARENTHESES

JCL error. An expected parenthesis was not received.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0450E job-number job-name REFERENCED DD DOES NOT REFER TO A PDS MEMBER

A reference such as PGM=*.step.pste.ddname refers to a DD name that does not reference a PDS member.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0453E job-number job-name UNKNOWN RESTART STEP NAME

JCL error. The step name specified in the RESTART operand of the JOB statement cannot be resolved.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0454E job-number job-name INVALID ABEND CODE

JCL error. The abend code in an IF statement or in the COND operand of the JOB or EXEC statement is specified incorrectly.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0455E job-number job-name INVALID BLKSIZE OPERAND

JCL error. The BLKSIZE operand is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0456I job-number job-name BLKSIZE NOT A MULTIPLE OF LRECL

JCL error. BLKSIZE must be a multiple of LRECL when both are coded and when RECFM=fixed is specified or implied.

The error has been ignored, but the associated data set may be unusable.

Resolution:

If necessary, correct the error and resubmit the job.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0457E job-number job-name INVALID EXPDT VALUE

JCL error. The value specified for EXPDT is improperly coded or is not within the acceptable range.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0458W job-number job-name INVALID FREE VALUE – DEFAULT OF (END) SUBSTITUTED

JCL error. The value specified for FREE is improperly coded or is not within the acceptable range.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0459E job-number job-name INVALID UCS VALUE

JCL error. The value specified for UCS is improperly coded or is not within the acceptable range.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0460E job-number job-name INVALID RECORG VALUE

JCL error. The value specified for RECORG must be KS, ES, or RR.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0461E job-number job-name INVALID DLM VALUE

JCL error. The value specified for DLM is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0462E job-number job-name INVALID AVGREC VALUE

JCL error. The value specified for AVGREC is improperly coded or is not within the acceptable range.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0463E job-number job-name TOO MANY LIBRARIES SPECIFIED

JCL error. More than 15 libraries were specified on the JCLLIB statement.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0464E job-number job-name INCLUDE NOT FOUND

JCL error. The data set specified in the INCLUDE statement was not found.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0465E job-number job-name DUPLICATE INSTREAM PROCEDURE

JCL error. The instream procedure name is a duplicate of one already used.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0499S job-number job-name FILE I/O ERROR OR FILE IS EMPTY

There was an I/O error trying to read the referenced cataloged procedure or JCL included file, or the file is empty.

Resolution:

Verify that the correlated PC file exists, that it is not empty, and that the attributes specified in the system catalog match the physical characteristics of the file.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0900E job-number job-name User Exit shut down due to a failure

A failure in the user exit has forced the JCL engine to shut down the user exit.

The user exit will not be notified of any future events for this job.

Resolution:

Correct the problems in the user exit and re-run.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0901I job-number job-name Event-job-ready action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0902I job-number job-name Event-job-flushed action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0903I job-number job-name Event-job-started action is: explanation

The user exit has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0904I job-number job-name Event-job-JCL-error action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0905I job-number job-name Event-job-ended action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0906I job-number job-name Event-TSO-started action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0907I job-number job-name Event-TSO-ended action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0908I job-number job-name Event-step-ready action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0909I job-number job-name Event-step-started action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0910I job-number job-name Event-step-ended action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0911I job-number job-name Event-step-bypassed action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0912I job-number job-name Event-CALL-ready action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0913I job-number job-name Event-CALL-started action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0914I job-number job-name Event-CALL-ended action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0915I job-number job-name Event-RUN-ready action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0916I job-number job-name Event-RUN-started action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0917I job-number job-name Event-RUN-ended action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0918I job-number job-name Event-before-PGM-call action is: explanation

The user exit has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0919I job-number job-name Event-after-PGM-call action is: explanation

The user exist has requested this action to be taken for this event.

Resolution:

No action is required.

Parent topic: JCLCM0900 - JCLCM0999


JCLGN0001U job-number job-name MISSING SYSUT1

The DD statement for SYSUT1 is missing from your JCL.

Resolution:

Include a DD statement for SYSUT1 and try again.

Parent topic: JCLGN Error Messages


JCLGN0002U job-number job-name INVALID SYSUT1

The dataset organization for SYSUT1 is invalid.

Only sequential datasets and members of a PDS dataset can be specified on the SYSUT1DD statement.

Resolution:

Correct the DD statement for SYSUT1 and try again.

Parent topic: JCLGN Error Messages


JCLGN0003U job-number job-name MISSING SYSUT2

The DD statement for SYSUT2 is missing from your JCL.

Resolution:

Include a DD statement for SYSUT2 and try again.

Parent topic: JCLGN Error Messages


JCLGN0004U job-number job-name INVALID SYSUT2

The dataset organization for SYSUT2 is invalid. Only sequential datasets and members of a PDS dataset can be specified on the SYSUT2DD statement.

Resolution:

Correct the DD statement for SYSUT2 and try again.

Parent topic: JCLGN Error Messages


JCLGN0005U job-number job-name I/O ERROR ON SYSUT1

An error has occurred when accessing the dataset specified by the SYSUT1DD statement.

Resolution:

Verify that DCB characteristics specified on the SYSUT1DD statement, if any, and the DCB characteristics in the system catalog for the data set name specified on the SYSUT1DD statement are correct.

Parent topic: JCLGN Error Messages


SORT014U job-number job-name STATUS = FILE STATUS

The specified file status values indicate the cause of the I/O error reported in message SORT013U.

Resolution:

File I/O errors are often caused by defining improper values for record formats. For example, you might have defined a line sequential data set (LSEQ) as a record sequential data set.

Parent topic: SORT000 - SORT099
Related information
SORT013U job-number job-name I/O ERROR ON DATASET 'DATASET'


SORT015U job-number job-name COMMAND STATEMENT ERROR(S) DETECTED

Errors have been detected during SYSIN command statement processing.

Resolution:

Correct the errors and try again.

Parent topic: SORT000 - SORT099


SORT016I job-number job-name SORTTEMP DATASET ALLOCATED TO 'FILE'

The temporary sort work file has been allocated to the specified file. The temporary file name is obtained from the operating system and appended with a $WK file name extension.

Temporary work files are allocated to the path name specified in the MFJSORTW environment variable. If MFJSORTW is not specified, the temporary files are allocated to the directory specified in the TEMP environment variable, and to the current drive and directory when neither is specified.

The temporary file name format is hhmmssss.$WK, where hhmmssss is the system time of file allocation.

Parent topic: SORT000 - SORT099


SORT019I job-number job-name KEY LENGTH TRUNCATED TO 4096 BYTES

The concatenated key length exceeds 4096 bytes. Processing continues, however the sort/merge operation uses only the first 4096 bytes of the key field(s) specified.

Resolution:

Check the key field(s) specified for the sort/merge operation.

Parent topic: SORT000 - SORT099


SORT020U job-number job-name SORT(EXTSM) FAILED – SORT ENGINE STATUS = EXTSM STATUS

The size of the files which can be sorted or merged by MFJSORT(EXTSM) is determined by the record length, number of sort fields, sort field lengths, the amount of memory available, and the amount of disk space available for virtual paging.

Resolution:

Make additional real or virtual memory available, or reduce the file size or the number and length of sort/merge fields, and retry the sort/merge operation. Contact SupportLine if the problem persists.

Parent topic: SORT000 - SORT099


SORT033I job-number job-namenumber RECORDS MERGED

This message indicates the number of records actually written to the SORTOUT output data set by the MERGE function.
Parent topic: SORT000 - SORT099


SORT034I job-number job-namenumber RECORDS COPIED

This message indicates the number of records actually written to the SORTOUT output data set by the COPY function.
Parent topic: SORT000 - SORT099


SORT035U job-number job-name SORTIN DSORG OR RECFM MISSING

The record format for the SORTIN data set is missing.

Resolution:

Correct the catalog entry for the SORTIN data set to include the record format (RECFM).

Parent topic: SORT000 - SORT099


SORT036U job-number job-name SORTIN RECORD LENGTH MISSING OR INVALID

The record length for the SORTIN data set is missing.

Resolution:

Correct the catalog entry for the SORTIN data set to include the logical record length (LRECL).

Parent topic: SORT000 - SORT099


SORT037U job-number job-name SYSIN RECFM 'FORMAT'' INVALID

The record format for the SYSIN data set is invalid.

Resolution:

Correct the catalog entry for the SYSIN data set to include a valid record format (RECFM).

Parent topic: SORT000 - SORT099


SORT038U job-number job-name SORTIN RECFM 'FORMAT' INVALID

The record format for the SORTIN data set is invalid.

Resolution:

Correct the catalog entry for the SORTIN data set to include a valid record format (RECFM).

Parent topic: SORT000 - SORT099


SORT039U job-number job-name SORTOUT RECFM 'FORMAT' INVALID

The record format for the SORTOUT data set is invalid.

Resolution:

Correct the catalog entry for the SORTOUT data set to include a valid record format (RECFM).

Parent topic: SORT000 - SORT099


SORT040U job-number job-name SORT TERMINATED BY E15 'PROGRAM'

The user E15 exit has requested termination of the sort/merge operation.
Parent topic: SORT000 - SORT099


SORT041U job-number job-name SORT TERMINATED BY E35 'PROGRAM'

The user E35 exit has requested termination of the sort/merge operation.
Parent topic: SORT000 - SORT099


SORT042U job-number job-name MEMORY ALLOCATION FAILURE

The system has run out of memory during the sort process.

Resolution:

Close down some other active programs and try again.

Parent topic: SORT000 - SORT099


SORT043U job-number job-name TOO MANY OUTFIL FILES SPECIFIED

The limit of 16 OUTFIL files has been exceeded.

Resolution:

Reduce the number of OUTFIL files.

Parent topic: SORT000 - SORT099


SORT044U job-number job-name TOO MANY 'USE' FILES SPECIFIED

The limit of 16 USE files has been exceeded (non-emulation mode).

Resolution:

Reduce the number of USE files.

Parent topic: SORT000 - SORT099


SORT045U job-number job-name TOO MANY 'GIVE' FILES SPECIFIED

The limit of 16 GIVE files has been exceeded (non-emulation mode).

Resolution:

Reduce the number of GIVE files.

Parent topic: SORT000 - SORT099


SORT090U job-number job-name SORT TERMINATED - MISSING SYSOUT

The DD statement for the SYSOUT data set cannot be located.

Resolution:

Specify a SYSOUT DD statement and try again.

Parent topic: SORT000 - SORT099


SORT091U job-number job-name SORT TERMINATED - MISSING SYSIN

The DD statement for the SYSIN data set cannot be located.

Resolution:

Specify a SYSIN DD statement and try again.

Parent topic: SORT000 - SORT099


SORT092U job-number job-name SORT TERMINATED - MISSING SORTOUT

The DD statement for the SORTOUT data set cannot be located.

Resolution:

Specify a SORTOUT DD statement and try again.

Parent topic: SORT000 - SORT099


SORT093U job-number job-name SORT TERMINATED - MISSING SORTIN OR SORTIN01

The DD statement for a SORTIN or SORTIN01 data set cannot be located.

Resolution:

Specify a SORTIN or SORTIN01 DD statement and try again.

Parent topic: SORT000 - SORT099


SORT094U job-number job-name SORT TERMINATED - MISSING SORTOFnn

The DD statement for a SORTOF data set referenced by the OUTFIL control statement cannot be located.

Resolution:

Specify a SORTOFnn DD statement and try again.

Parent topic: SORT000 - SORT099


SORT095U job-number job-name SORT TERMINATED – BAD DATA IN 'CHANGE' FIELD

Input data did not match any of the CHANGE find-constants and the NOMATCH option was not specified.

Resolution:

Change the sort request, using the NOMATCH option to specify the action to be taken when input data does not match any of the CHANGE find-constants.

Parent topic: SORT000 - SORT099


SORT096U job-number job-name SORT TERMINATED – MISSING FNAMES DATASET 'DATASET'

The DD statement for the FNAMES data set cannot be located.

Resolution:

Specify a DD statement and try again.

Parent topic: SORT000 - SORT099


SORT110E job-number job-name NON-NUMERIC DATA DETECTED

Numeric data is expected at the specified column.

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT111E job-number job-name 'OPERATOR' OPERATOR ALREADY PROCESSED

The specified operator (at the specified column) has already been processed.

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT112E job-number job-name 'EXIT'' EXIT NOT SUPPORTED

The specified exit (at the specified column) is not supported. Only the E15 and E35 exits are supported by MFJSORT.

Resolution:

Check the exit name. You might have misspelled it.

Parent topic: SORT100 - SORT199


SORT114E job-number job-name EXPECTED '(' NOT FOUND

A left parenthesis is expected at the specified column but has not been found.

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT115E job-number job-name BOOLEAN OPERATOR 'OPERATOR' INVALID

The specified Boolean operator (at the specified column) is invalid. Valid Boolean operators are EQ, NE, LT, LE, GT, and GE.

Resolution:

Correct the Boolean operator and try again.

Parent topic: SORT100 - SORT199


SORT118E job-number job-name SORT / MERGE CONFLICT

Both SORT and MERGE commands have been found; only one can be specified. The second command is at the specified column.

Resolution:

Correct the command statements and try again.

Parent topic: SORT100 - SORT199


SORT119E job-number job-name INCLUDE / OMIT CONFLICT

Both INCLUDE and OMIT commands have been found; only one can be specified. The second command is at the specified column.

Resolution:

Correct the command statements and try again.

Parent topic: SORT100 - SORT199


SORT120E job-number job-name SORT STATEMENT MISSING FIELDS OPERAND

The SORT command statement does not contain a FIELDS operand.

Resolution:

Correct the SORT statement and try again.

Parent topic: SORT100 - SORT199


SORT121E job-number job-name MERGE STATEMENT MISSING FIELDS OPERAND

The MERGE command statement does not contain a FIELDS operand.

Resolution:

Correct the MERGE statement and try again.

Parent topic: SORT100 - SORT199


SORT122E job-number job-name INCLUDE STATEMENT MISSING COND OPERAND

The INCLUDE command statement does not contain a COND operand.

Resolution:

Correct the INCLUDE statement and try again.

Parent topic: SORT100 - SORT199


SORT123E job-number job-name OMIT STATEMENT MISSING COND OPERAND

The OMIT command statement does not contain a COND operand.

Resolution:

Correct the OMIT statement and try again.

Parent topic: SORT100 - SORT199


SORT124E job-number job-name FIELD POSITION 'NUMBER' INVALID

The specified field position is invalid. Field positions can start at 1 but must not exceed the length of the SORTIN record, allowing for the length of the control field.

Resolution:

Correct the field position and try again.

Parent topic: SORT100 - SORT199


SORT125E job-number job-name FIELD LENGTH 'NUMBER' INVALID

The field length specified is too long. Control fields are limited to 1024 bytes in length. Byte(.bit) notation is not supported.

Resolution:

Correct the field length and try again.

Parent topic: SORT100 - SORT199


SORT126E job-number job-name RECORD LENGTH 'NUMBER'' INVALID

The specified record length is invalid. Record lengths may not exceed 32768 bytes.

Resolution:

Correct the record length and try again.

Parent topic: SORT100 - SORT199


SORT127E job-number job-name MISSING SORT/MERGE/COPY COMMAND STATEMENT

A SORT, MERGE, or COPY command statement is required.

Resolution:

Include a SORT, MERGE, or COPY command statement and try again.

Parent topic: SORT100 - SORT199


SORT128E job-number job-title EXPECTED ')' NOT FOUND

A closing parenthesis ')' was expected and not found.

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT129E job-number job-name EXPECTED '=' NOT FOUND

'=' was expected and not found.

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT130E job-number job-name EXPECTED 'F' OR 'V' NOT FOUND

Either F or V must be specified to indicate recording mode (non-emulation mode).

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT131E job-number job-name EXPECTED 'IX', 'RL', 'SQ', OR 'LS' NOT FOUND

Organization must be specified as either IX, RL, SQ or LS (non-emulation mode).

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT132E job-number job-name PRIME KEY MUST BE SPECIFIED FIRST

When specifying keys for a USE OR GIVE indexed file (non-emulation mode), the prime key must be specified first.

Resolution:

Reorder the key definitions so that the prime key is first and try again.

Parent topic: SORT100 - SORT199


SORT133E job-number job-name EXPECTED 'P', 'AD', 'A', OR 'C' NOT FOUND

Key type for a USE OR GIVE indexed file must be specified as one of P (primary), AD (alternate permitting duplicates) A (alternate not permitting duplicates) or C (component).

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT134E job-number job-name KEYWORD/VALUE 'VALUE' INVALID FOR DFSORT EMULATION

The specified keyword is not valid for DFSORT emulation.

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT135E job-number job-name KEYWORD/VALUE 'VALUE' INVALID FOR SYNCSORT EMULATION

The specified keyword is not valid for SYNCSORT emulation.

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT136E job-number job-name NO GIVE FILE SPECIFIED FOR OUTFIL GROUP

No GIVE file has been specified for the current OUTFIL group (non-emulation mode).

Resolution:

Specify a GIVE file for the group and try again.

Parent topic: SORT100 - SORT199


SORT137E job-number job-name NO USE FILE SPECIFIED

No USE file has been specified for the SORT (non-emulation mode).

Resolution:

Specify a USE file and try again.

Parent topic: SORT100 - SORT199


SORT138E job-number job-name TARGET LITERAL 'LITERAL' TOO LONG IN CHANGE

The set-constant in a CHANGE statement must not be longer than the specified length of the output field to be inserted (v).

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT197E job-number job-name INREC / MERGE CONFLICT

The INREC command (at the specified column) cannot be used with MERGE operations.

Resolution:

Substitute a SORT command instead of MERGE and try again.

Parent topic: SORT100 - SORT199


SORT198E job-number job-name NON-NUMERIC DATA DETECTED IN 'ZD' SUM FIELD

Non-numeric data has been found in a field specified as zoned decimal.

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT199E job-number job-name TOO MANY OUTFIL STMTS OR TOO MANY FIELDS ON OUTFIL STMT(S)

More than 16 SORTOFnn files are specified by the OUTFIL command(s).

Resolution:

Reduce the number of SORTOFnn files and try again.

Parent topic: SORT100 - SORT199


SORT205I: job-number job-name INPUT file 'ddname'

Informational message showing the name of the input file for the SORT operation just performed.
Parent topic: SORT200 - SORT399
Related information
MFJSORT Summary Messages


SORT206I: job-number job-name OUTPUT file 'ddname'

Informational message showing the name of the output file for the SORT operation just performed.
Parent topic: SORT200 - SORT399
Related information
MFJSORT Summary Messages


SORT207I: job-number job-name OUTFIL file 'ddname '

Informational message showing the name of the output file for the SORT operation just performed.
Parent topic: SORT200 - SORT399
Related information
MFJSORT Summary Messages


SORT301E: job-number job-name Position/Length bit specification ' byte.bit' must be >= 0 and <= 7.

The bit portion of the byte.bit position or length specification must be between 0 and 7.

Resolution:

Correct the error and re-run.

Parent topic: SORT200 - SORT399


SORT399I: job-number job-name End of Micro Focus MFJSORT Utility.

Informational message indicating the end of the SORT process.
Parent topic: SORT200 - SORT399
Related information
MFJSORT Summary Messages


JCLCM0199I job-number job-name Program program-name is cobol-dialectchar-setbyte-orderamode-type

The program program-name, which is being executed, has the stated characteristics.
cobol-dialect
One of:
  • COBOL ANS85
  • COBOL VSC2
  • COBOL OSVS
  • Z/OS HLASM
  • non-COBOL
char-set
One of:
  • ASCII
  • EBCDIC
byte-order
One of:
  • Big-Endian
  • Little-Endian
amode-type
One of:
  • AMODE31
  • AMODE24
  • NOAMODE
Parent topic: JCLCM0000 - JCLCM0199


JCLCM0164A job-number job-name All job numbers in the range lower-job-number:upper-job-number are in use.

The system has used up all available job numbers and cannot process this job.

The job has been rejected. The range in effect is indicated by lower-job-number and upper-job-number.

Resolution:

The administrator should purge jobs and spool files that are no longer needed. Until more job numbers become available, all future job submissions will be rejected with this message.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0180I job-number job-name Job ready for execution.

The job named is ready for execution.
Parent topic: JCLCM0000 - JCLCM0199


JCLAM0116S UNEXPECTED RETURN CODE FROM MVSCATIO [return-code]

An internal error has been detected by MVSCATIO.

Resolution:

Note the return code and contact Micro Focus Support.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0149S INVALID QUOTED LITERAL

The literal contains an uneven number of quotation marks.

Resolution:

Make sure any quotation marks within the literal are doubled. For example, This is Jane''s book (two consecutive single quotation marks). If the literal is continued onto a second line make sure the first line has a terminating literal.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0150S ERROR. FILE IS EMPTY

You are trying to copy from an empty file.

Resolution:

Make sure the sending file is not empty.

Parent topic: JCLAM0140 - JCLAM 0159


JCLAM0164S Left parenthesis missing after "keyword"

Parent topic: JCLAM0160 - JCLAM0179


JCLAM0165S Unrecognizable keyword "keyword"

You have used a non-existent keyword, or one that is not supported.

Resolution:

Check your syntax and spelling.

Parent topic: JCLAM0160 - JCLAM0179


JCLAM0166S A required keyword must follow "keyword"

You have failed to use a keyword where it is required.

Resolution:

Check your syntax and spelling.

Parent topic: JCLAM0160 - JCLAM0179


JCLAM0167S Command "%" is not supported

The command is not implemented.
Parent topic: JCLAM0160 - JCLAM0179


JCLAM0168S Invalid keyword value "value"

The value is not of the required type or range.
Parent topic: JCLAM0160 - JCLAM0179


JCLAM0169I The "command-name" command is not required. Command ignored

This command is not needed in the Micro Focus environment.

The job should function the same without the command.

Resolution:

Remove the command if you wish, or leave it there for mainframe compatibility.

Parent topic: JCLAM0160 - JCLAM0179


JCLAM0170I Use host compatible form: "extension-name"

You have used a Micro Focus JCL extension without a preceding %.

This works in the Micro Focus environment but is not mainframe compatible.

Resolution:

We recommend replacing PCDSN with %PCDSN for mainframe compatibility.

Parent topic: JCLAM0160 - JCLAM0179


JCLAM0171S Password is not permitted here "level"

LEVEL does not allow a password.
Parent topic: JCLAM0160 - JCLAM0179


JCLAM0000I job-number job-name Interactive AMS Terminated

The MFJAMS utility has terminated.

This does not imply an error. It could occur, for example, if a debugging session is canceled while the utility is in use.

Resolution

No action is required.

Parent topic: JCLAM0000 - JCLAM0119


JCLAM0179S Unable to obtain access to "dataset-name"

System cannot obtain access to the specified dataset.

It is probably being used by another job or user with exclusive access.

Parent topic: JCLAM0160 - JCLAM0179


JCLAM0180S Unexpected return code return-code from jseb-func-enq-ds

Indicates an internal error detected by jseb-func-enq-ds.

Resolution:

Note the return code and contact SupportLine. Reproducing the issue with CTF trace enabled may be necessary to establish the cause of the error and can provide more information for customer support.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0181S Unexpected return code % from jseb-func-deq-ds

Indicates an internal error detected by jseb-func-deq-ds.

Resolution:

Note the return code and contact SupportLine.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0182U Unexpected return code % from jseb-func-info-job

Indicates an internal error detected by jseb-func-info-job.

Resolution:

Note the return code and contact SupportLine.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0183S Character set mismatch. Copied without conversion

You are trying to copy an ASCII dataset to an EBCDIC one, or vice versa.
Parent topic: JCLAM0180 - JCLAM0230


JCLAM0184I OS Copy used to perform this REPRO

Informational only.

Resolution:

No action is required.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0185S OS Copy operation for this REPRO failed with RC=return-code

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0186I Incompatible data set attributes. OSCOPY ignored.

A full copy operation was done, instead of using the copy facility provided by the operating system as you requested.

Resolution:

No action is required.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0228I Record n out of key sequence.

The record has a key that is less than or equal to the key of the previous record.

Resolution:

No action is required.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0229E Record n out of key sequence.

The record has a key that is less than or equal to the key of the previous record.

Resolution:

Correct the order of the records so that the keys are sequential, and re-run.

Parent topic: JCLAM0180 - JCLAM0230


JCLCM0169I JCL copied

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0196S Resource allocation failed for dd-name<[concat dd seq no]>. Reason=nnn

This is usually preceded by another JCLCM message providing additional information.

The meanings of the reason codes are as follows:

  • 001 - invalid mvs dataset name
  • 002 - invalid recfm and dsorg combination
  • 003 - invalid recfm, lrecl and dsorg combination
  • 004 - invalid lrecl
  • 005 - no gdg model present
  • 006 - gdg max < 1 or > 99
  • 007 - gdg roll disp is incorrect
  • 008 - charset is not ascii, ebcdic or unknown
Parent topic: JCLCM0000 - JCLCM0199


JCLCM0198I VSE CONFIG FILE - outcome : config-file

Tells you the outcome of your attempt to load an optional VSE JCL configuration file (specified by the VSE_STARTUP_CFG environment variable).

outcome can be LOADED (indicating that the configuration file was read sucessfully), NOT SPECIFIED (no configuration file was specified), or UNAVAILABLE (the specified configuration file could not be read).

Resolution:

No action is required if the outcome is as you expected. Otherwise, make sure the file is specified and available.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0203S ACI option has overridden step abend S422

You have requested the Automatic Catalog Input option, and therefore an S422 abend has been ignored.

Resolution:

Investigate the abend. One possible cause is that a data set used by the step does not exist on the host.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0214S Required resources could not be obtained

All the required datasets for this job are unavailable. Probably some other job or user is using them.

Resolution:

Try again later.

Parent topic: JCLCM0200 - JCLCM0299


JCLAM0124I job-number job-name GDG LIMIT CHANGED TO 31

You have requested more than the maximum number of GDG entries allowed.

Resolution

Reduce the number of entries requested to 31 or fewer and try again. The minimum number is 1.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0125S job-number job-name RELATENAME NOT CATALOGED [ENTRYNAME]

The dataset specified by RELATENAME must exist before an alternate index can be defined.

The dataset is not cataloged.

Resolution:

Correct the dataset name or define the dataset and try the operation again.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0126S job-number job-name FILE MISSING OR INVALID TYPE [FILENAME]

The specified workstation file cannot be located.

Resolution:

Make sure the VSAM file is complete and try the operation again.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0127I job-number job-name ALTERNATE INDEX DEFINED [ENTRYNAME]

The alternate index has been defined. The appropriate workstation file has been updated to reflect the new index keys.
Parent topic: JCLAM0120 - JCLAM0139


JCLAM0128I job-number job-nameNUMBER RECORDS INDEXED

The keys for the specified number of records have been added for the newly-defined alternate index.
Parent topic: JCLAM0120 - JCLAM0139


JCLAM0129S job-number job-name INVALID PRIMARY KEY OR RECORDSIZE

The key position plus the key length exceeds the defined record length.

Resolution:

Correct the record length or key position and try again.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0130S job-number job-name DD MISSING [DDNAME]

A DD statement for the specified DD name is not defined in your JCL.

Resolution:

Add the necessary statement for the DD name or correct the DD name specified in the INFILE or OUTFILE parameter and try again.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0131S job-number job-name INSUFFICIENT DCB [DATASETNAME]

The specified dataset does not have complete data control block characteristics.

Resolution:

Provide the required DCB parameters in your JCL or update the catalog to include all of the DCB parameters. A valid RECFM and LRECL is required.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0132S job-number job-name I/O ERROR [DATASETNAME]

Resolution

See message JCLAM0133S for information on the I/O operation that caused the error.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0133S job-number job-name I/O STATUS [FILE STATUS]

Resolution:

File I/O errors are generally caused by defining incorrect values for record formats. For example, defining a line sequential dataset (LSEQ) as a record sequential dataset. Correct the values and retry the operation.

Parent topic: JCLAM0120 - JCLAM0139


JCLAM0162S job-number job-name Mutually exclusive keywords specified

Only one of these keywords is permitted.

Resolution:

Specify only the desired keyword and re-run.

Parent topic: JCLAM0160 - JCLAM0179


JCLAM0163S job-number job-name The "*" specification must be surrounded by dots

The * specification must be preceded and followed by a period.

For example, MFIDSA.PAYROLL.* is invalid since it is not followed by a period.

Resolution:

Correct and re-run.

Parent topic: JCLAM0160 - JCLAM0179


JCLCM0000I job-number job-name JCL PROCESSOR TERMINATED

The JCL processor has terminated. This does not imply an error. It could occur, for example, if a debugging session is cancelled while a jobstream is being processed.

Resolution:

No action is required.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0001U job-number job-name I/O ERROR ON SYSTEM CATALOG FILE

Configuration error.

Resolution:

If running under the IDE, contact SupportLine. If running from a Micro Focus command prompt, correct the setting for the MFSYSCAT environment variable.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0147U job-number job-name NO DATASET NAME SPECIFIED

The function requested requires a data set name to be specified.

Resolution:

Ensure that a data set name has been specified and try again. Contact SupportLine if the problem persists.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0158U job-number job-name MVS data set "name" not found

The specified MVS data set is not in the catalog.

Resolution:

Add the data set to the catalog and re-run.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0159U job-number job-name FILE OPEN ERROR FILENAME

There was an open error on the main source file submitted to the JCL scanner for processing.

Resolution

Verify that the file exists, that it is not empty, and that it has been correlated properly in the system catalog if it is not a line sequential file.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0160U job-number job-name FILE I/O ERROR FILENAME

There was an I/O error on the main source file submitted to the JCL scanner for processing.

Resolution:

Verify that the file exists, that it is not empty, and that it has been correlated properly in the system catalog if it is not a line sequential file.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0161U job-number job-name DATASET TYPE INVALID DATASETNAME

The specified data set is of a type that cannot be used for the requested function.

For example, you cannot submit a GDG or PDS model name as a JCL jobstream because the contents of the data set are not recognized as JCL.

Resolution:

Verify that the data set name is correct and that the correct DCB attributes have been specified in the system catalog.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0162U job-number job-name FILE IS EMPTY FILENAME

The specified file is empty. The function you have attempted cannot be performed on an empty data set or file.

Resolution:

Verify whether the data set is empty and that the correct DCB attributes have been specified in the system catalog.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0205I job-number job-namePROGRAM FUNC=func/functext RC=rcode/rcodetext

The specified program has detected an unexpected return code from the MVS Job Step Resource Manager (MJRM). Details of the function and return code are provided in the message.

Resolution:

Contact SupportLine. Reproducing the issue with CTF trace enabled may be necessary to establish the cause of the error and can provide more information for customer support.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0206I job-number job-name ALLOCATION DEFERRED UNTIL OPEN - DDNAME

In the specified DD statement, the first (or only) data set specified does not exist and the step being executed is an IMS batch step.

Allocation of any data sets for the DD statement is deferred until data set open time to prevent generation of JCL errors for DD statements which may be associated with IMS databases, as they are not required by the IMS component.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0207I job-number job-name DUPLICATE DD STATEMENT IGNORED - DDNAME

The specified DD statement is a duplicate of a DD statement defined earlier in the job step.

Resolution:

Delete the duplicate DD statement to avoid this message in future.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0208I job-number job-name Host OS may require SPACE for DD "DD-name"

The host operating system (MVS, OS/390, z/OS) might require that you specify the SPACE parameter unless the data set is allocated to a device such a tape device.

Resolution:

Change the JCL to run on the host if appropriate.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0209S job-number job-name DISP=NEW, UNCATALOGED DUPLICATE EXISTS - DDNAME

The specified DD statement specifies DISP=NEW but the data set name specified already exists in the catalog (in an uncataloged state).

Resolution:

This condition can arise when DISP=(NEW,KEEP) or DISP=(,UNCATLG) is specified or implied. Select the Catalog View, check the Show uncataloged datasets check box, and review the entries listed. Delete the duplicate data set entry in the catalog, or correct the disposition or data set name in the JCL as appropriate.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0210U job-number job-name I/O ERROR ON SPOOL FILE

An I/O error has occurred while accessing the spool file containing JOB output.

Resolution:

Contact SupportLine.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0211S job-number job-name Dataclass "name" does not exist

This specified data class has not been defined to this system.

Resolution:

Correct the name and retry, or define the data class with this name.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0212S job-number job-name REFDD dataclass "name" does not exist

This specified data class has not been defined to this system.

Resolution:

Correct the name and retry, or define the data class with this name.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0213S job-number job-name Main pgm name did not issue GOBACK or STOP RUN

The specified main COBOL program fell through to the end of the program without executing a GOBACK or a STOP RUN statement.

Resolution:

Correct as appropriate and re-run.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0401U job-number job-name MISSING JOB STATEMENT

JCL error. A JOB statement is required in the jobstream.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0429E job-number job-name INVALID CONDITION OPERATOR

JCL error. The condition operator is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0430E job-number job-name INVALID PROGRAM NAME

The program name is improperly coded.

Specify a program name of 1 to 8 alphanumeric or national characters in the PROGRAM field. The first character must be alphabetic or national.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0431E job-number job-name INVALID DYNAMNBR OPERAND

JCL error. The DYNAMNBR operand is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0432E job-number job-name INVALID BURST OPERAND

JCL error. The BURST operand is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0433E job-number job-name INVALID CHKPT OPERAND

JCL error. The CHKPT operand is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0434E job-number job-name INVALID RECFM OPERAND

JCL error. The RECFM operand is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0435E job-number job-name INVALID LRECL OPERAND

JCL error. The LRECL operand is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0436E job-number job-name INVALID DISP OPERAND

JCL error. The DISP operand is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0437E job-number job-name UNEXPECTED STATEMENT

JCL error. The JCL statement received was not expected.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0438E job-number job-name PROCSTEP NOT FOUND

JCL error. The procedure step name referenced cannot be located.

Resolution:

Make sure the name refers to a valid procedure step.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0466U job-number job-name INVALID JOBNAME

JCL error. The job name specified is invalid.

Resolution:

Check the job name to make sure it follows the MVS naming rules.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0467E job-number job-name CONFLICTING OR INCOMPATIBLE OPERANDS

JCL error. Conflicting operands have been included on the JCL statement.

For example, you cannot specify DCB= and LIKE= and REFDD= all on the same DD statement.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0468E job-number job-name INVALID DSORG VALUE

JCL error. The value specified for DSORG is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0469I job-number job-name NONUNIQUE REFERENCE RESOLVED TO FIRST OCCURRENCE

JCL error. This message indicates that there are multiple job steps with the same name as the referenced stepname.

The JCL processor has assumed that the use of that stepname refers to the first job step which has that stepname.

Resolution:

Check that the default action is appropriate.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0470I job-number job-name NONUNIQUE REFERENCE RESOLVED TO CURRENT OCCURRENCE

JCL error. This message indicates that there are multiple job steps with the same name as the referenced stepname.

The JCL processor has assumed that the use of that stepname refers to the current job step which has that stepname.

Resolution:

Check that the default action is appropriate.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0471E job-number job-name OPERAND TABLE LIMIT EXCEEDED

JCL error. The limit on the number of operands supported has been exceeded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0472E job-number job-name SYMBOL TABLE LIMIT EXCEEDED

JCL error. The limit on the number of symbols supported has been exceeded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0473E job-number job-name INVALID NULL OPERAND VALUE

JCL error. A keyword operand with no value was specified, but a value is required.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0474E job-number job-name INVALID SYSOUT CLASS OPERAND

JCL error. The SYSOUT class operand on the DD statement is improperly coded.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0476E job-number job-name Symbol "name" was not used

The specified symbol is not used anywhere in the procedure. One explanation is that the symbol is misspelled.

Resolution:

Correct the error and resubmit the jobstream.

Parent topic: JCLCM0400 - JCLCM0499


JCLGN0006U job-number job-name I/O ERROR ON SYSUT2

An error has occurred when accessing the dataset specified by the SYSUT2DD statement.

Resolution:

Verify that DCB characteristics specified on the SYSUT2DD statement, if any, and the DCB characteristics in the system catalog for the data set name specified on the SYSUT2DD statement are correct.

Parent topic: JCLGN Error Messages


JCLIM0001U job-number job-name INVALID EXEC STATEMENT PARM

MFJIMS expects parameter data on the EXEC statement, but the data has not been supplied.

Resolution:

Specify the parameter data and try again. The format of the PARM operand is:
PARM = ' type , programname , psbname '
Parent topic: JCLIM Error Messages


JCLIM0002U job-number job-name INVALID PROGRAM TYPE PARM

The program type specified in the PARM operand must be BMP (or IFP) or DLI (or DBB).

Resolution:

Correct the program type in the PARM operand of the EXEC statement and try again.

Parent topic: JCLIM Error Messages


JCLIM0003U job-number job-name MISSING PROGRAM NAME PARM

The program name has not been specified in the PARM operand.

Resolution:

Specify a program name in the PARM operand of the EXEC statement and try again.

Parent topic: JCLIM Error Messages


JCLIM0004U job-number job-name MFIMS OPTION NOT INSTALLED

MFJRRC00 is unable to locate the MFIMS software option.

Resolution:

If necessary, install the MFIMS component. If it is already installed, contact SupportLine.

Parent topic: JCLIM Error Messages


SORT009U job-number job-name SORT TERMINATED - ERROR ACCESSING MFJSORTM.DAT

The message file cannot be found or it cannot be opened.

Another process might have the file open for exclusive use.

Resolution:

Retry the sort/merge operation.

Parent topic: SORT000 - SORT099


SORT012U job-number job-name SYSIN DATASET 'DATASET' EMPTY

MFJSORT has found the specified SYSIN data set to be empty. Processing is terminated.

Resolution:

Make certain that the SYSIN data set or instream SYSIN contains data.

Parent topic: SORT000 - SORT099


SORT013U job-number job-name I/O ERROR ON DATASET 'DATASET'

An I/O error has occurred on the specified data set.

Resolution:

See message SORT014U, which identifies the specific status code encountered.

Parent topic: SORT000 - SORT099
Related information
SORT014Ujob-number job-name STATUS=FILE STATUS


SORT100E job-number job-name MISSING OPERATOR

The SYSIN command statement does not contain a valid operator.

Resolution:

Correct the SYSIN command statement to include a valid operator.

Parent topic: SORT100 - SORT199


SORT101E job-number job-name MALFORMED OPERATOR

The SYSIN command statement operator (at the specified column) is invalid. A space must separate the operator from any operands.

Resolution:

Correct the SYSIN command statement to include a space after the operator.

Parent topic: SORT100 - SORT199


SORT102E job-number job-name EXPECTED OPERAND MISSING

A required operand is not present on the command statement.

Resolution:

Correct the command statement.

Parent topic: SORT100 - SORT199


SORT103E job-number job-name INVALID OPERATOR 'OPERATOR'

The command statement operator (at the specified column) is invalid.

Resolution:

Correct the command statement operator.

Parent topic: SORT100 - SORT199


SORT104E job-number job-name INVALID OPERAND KEYWORD 'OPERAND'

The command statement operand (at the specified column) is invalid.

Resolution:

Correct the command statement operand.

Parent topic: SORT100 - SORT199


SORT105E job-number job-name EXPECTED CONTINUATION NOT PRESENT

The command statement contains a continuation character in column 72, but the continuation text has not been found.

Resolution:

Check the command statement(s).

Parent topic: SORT100 - SORT199


SORT106E job-number job-name FIELD FORMATS IMPROPERLY SPECIFIED

The field format is incorrectly coded as a field-specific operand (for example, FIELDS=1,5,CH,A) and also as a global operand (for example, FORMAT=CH).

Resolution:

Specify the field format in one location only and try again.

Parent topic: SORT100 - SORT199


SORT107E job-number job-name FIELD FORMAT 'FORMAT' INVALID

The specified field format (at the specified column) is invalid. Valid field formats are AQ, BI, CH, FI, ZD, and PD.

Resolution:

Correct the field format and try again.

Parent topic: SORT100 - SORT199


SORT108E job-number job-name SEQUENCE 'SEQUENCE' INVALID

The sequence operand (at the specified column) must be A or D for ascending or descending sequences respectively.

Resolution:

Correct the sequence operand and try again.

Parent topic: SORT100 - SORT199


SORT109E job-number job-name TOO MANY FIELDS SPECIFIED

Control fields are limited to 16.

Resolution:

Reduce the number of control fields and try again.

Parent topic: SORT100 - SORT199


SORT139E job-number job-name SUBSTRING COMPARISON MUST BE WITH CHARACTER LITERAL

The right-hand side of a substring comparison must be a character literal.

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT140E job-number job-name INVALID BINARY DIGIT DETECTED

An invalid digit has been found in a binary literal. Valid digits are 0 and 1.

Resolution:

Correct the binary literal and try again.

Parent topic: SORT100 - SORT199


SORT141E job-number job-name CANNOT SPECIFY SAVE WITH EITHER INCLUDE OR OMIT

Only one of INCLUDE, OMIT or SAVE may be specified for any OUTFIL group.

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT142E job-number job-name REPEATED FILES= OR FNAMES=

Only one of FILES= or FNAMES= may be specified for any OUTFIL group.

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT191I job-number job-name OPERATOR 'OPERATOR' IGNORED

The specified operator (at the specified column) is not supported and has been ignored. Processing continues without error.
Parent topic: SORT100 - SORT199


SORT192I job-number job-name OPERAND 'OPERAND' IGNORED

The specified operand (at the specified column) is not supported and has been ignored. Processing continues without error.
Parent topic: SORT100 - SORT199


SORT193E job-number job-name INVALID HEX DIGIT DETECTED

An hexadecimal digit (0 - 9 or A - F) is expected at the specified column but has not been found.

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


SORT194I job-number job-name NO ALTSEQ COMMAND SPECIFIED FOR 'AQ' SORT FIELD FORMATS; 'CH' ASSUMED

A SORT control field requests an alternate collating sequence but no ALTSEQ command statement is specified. The standard collating sequence has been used instead. Processing continues without error.
Parent topic: SORT100 - SORT199


SORT195I job-number job-name SORTWORK DIRECTORY 'DIRECTORY' IS INVALID; USING CURRENT DIRECTORY

The MFJWORK or TEMP environment variable does not contain a valid device or directory path. The current directory has been used for temporary files instead. Processing continues without error.
Parent topic: SORT100 - SORT199


SORT196E job-number job-name SUM / COPY CONFLICT

The SUM command (at the specified column) cannot be used when the FIELDS=COPY statement is in effect.

Resolution:

Correct the command statement and try again.

Parent topic: SORT100 - SORT199


JCLUT0001E job-number job-name Control statement error explanation

Message

Control statement error "%1$s"

Where the parameter "%1$s" is a syntax hint.

Message information

Syntax Error. There is an error in the syntax of the control statement. The message will also contain a hint of the problem.

Resolution

Correct the syntax and resubmit the job.

Parent topic: JCLUT Error Messages


JCLUT0005E job-number job-name Continuation error

Message

Continuation error.

Message information

Syntax error.

Resolution

Correct the syntax and resubmit the job.

Parent topic: JCLUT Error Messages


JCLAM0172S System Error. Insufficient space in vcat for token

System error. token is a word or other token from the command, showing how far through processing the command the system had got when it ran out of space.

Resolution:

Contact SupportLine.

Parent topic: JCLAM0160 - JCLAM0179


JCLAM0173I Excess VOLUME specification "%" ignored

Resolution:

No action is required.

Parent topic: JCLAM0160 - JCLAM0179


JCLAM0174E keyword % in the DATA component is invalid

You have used a keyword that does not exist, or is not allowed in this context, or is not supported.

Resolution:

Check your syntax and spelling.

Parent topic: JCLAM0160 - JCLAM0179


JCLAM0175E keyword % in the INDEX component is invalid

You have used a keyword that does not exist, or is not allowed in this context, or is not supported.

Resolution:

Check your syntax and spelling.

Parent topic: JCLAM0160 - JCLAM0179


JCLAM0176I Data set dataset-name indexed

Informational only.

Resolution:

No action is required.

Parent topic: JCLAM0160 - JCLAM0179


JCLAM0177S Unexpected return-code return-code from CALLRB

Indicates an internal error detected by CALLRB

Resolution:

Note the return code and contact SupportLine.

Parent topic: JCLAM0160 - JCLAM0179


JCLAM0178S Unexpected status-code status-code from CALLRB

Indicates an internal error detected by CALLRB

Resolution:

Note the status code and contact SupportLine.

Parent topic: JCLAM0160 - JCLAM0179


JCLCM0216S Insufficient storage available to process the job

Either you have defined more data sets than the system can handle, or there is an internal error.

Resolution:

Contact SupportLine.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0217S Internal system error "internal code"

Internal error.

Resolution:

Contact SupportLine. Please mention the internal code.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0408I UNKNOWN OUTPUT STMT OPERAND IGNORED

You have used an unknown keyword.
Parent topic: JCLCM0400 - JCLCM0499


JCLCM0475I DD CHANGED TO DUMMY (DDNAME= MISSING)

You have referenced a file for which there is no DDNAME statement.

Resolution:

Add the required DDNAME statement to the JCL.

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0477S More than 255 EXEC statements

Parent topic: JCLCM0400 - JCLCM0499


JCLCM0500E SPACE parameter "value" is invalid or misplaced

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0501E UNIT parameter "value" is invalid or misplaced

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0502E VOLUME parameter "value" is invalid or misplaced

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0503E Invalid USER parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0504E TYPEXEC parameter "value" is invalid

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0505E DSNTYPE parameter "value" is invalid

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0506E account parameter or its length in error

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0507E programmer parameter or its length in error

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0508E Invalid ACCODE parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0509E Invalid CCSID parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0510E Invalid BYTES parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0511E Invalid CARDS parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0512E Invalid GROUP parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0513E Invalid LINES parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0514E Invalid NOTIFY parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0515E Invalid PAGES parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0516E Invalid PASSWORD parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0517E PARM parameter or its length in error

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0518E Invalid RESTART parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0519E Invalid SECLABEL parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0520E Invalid UPLOAD parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0521E Invalid DOWNLOAD parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0522E Invalid MEMBER parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0523E Invalid PCDSN parameter

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0524E COPIES parameter "value" has invalid value or syntax

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0525E Excess COPIES specification "value" rejected

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0526E FCB parameter "value" has invalid value

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0527E FLASH parameter "value" has invalid value

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0528E HOLD parameter "value" has invalid value

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0529E PRTSP parameter "value" has invalid value

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0530E SPIN parameter "value" has invalid value

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0531E TRTCH parameter "value" is invalid

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0532E "value" parameter is invalid

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0533E "value" parameter has invalid value

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0599I Excess VOLUME specification "value" ignored

Parent topic: JCLCM0500 - JCLCM0599


JCLCM0801I Event-job-concluded. Job ended normally

Parent topic: JCLCM0800 - JCLCM0899


JCLCM0802I Event-job-concluded. Job ended abnormally

Parent topic: JCLCM0800 - JCLCM0899


JCLCM0803I Event-job-concluded. Job failed - JCL error

Parent topic: JCLCM0800 - JCLCM0899


JCLCM0804I Event-job-concluded. Job scanned - No Errors

Parent topic: JCLCM0800 - JCLCM0899


JCLCM0805I Event-job-concluded. Job scanned - JCL error

Parent topic: JCLCM0800 - JCLCM0899


JCLCM0806I Event-job-concluded. Job flushed - No JOB stmt

Parent topic: JCLCM0800 - JCLCM0899


JCLCM0807I Event-job-concluded. Job flushed - Bad JOB stmt

Parent topic: JCLCM0800 - JCLCM0899


JCLCM0808I Event-job-concluded. Job flushed by User Exit req

Parent topic: JCLCM0800 - JCLCM0899


JCLCM0809I Event-job-concluded. Job copied

Parent topic: JCLCM0800 - JCLCM0899


JCLCM0810I Event-job-concluded. Job cancelled

Parent topic: JCLCM0800 - JCLCM0899


JCLCM0811I Event-job-concluded. Job authentication failed

Parent topic: JCLCM0800 - JCLCM0899


JCLGN0007U MISSING SYSPRINT

Parent topic: JCLGN Error Messages


JCLGN0008U INVALID SYSPRINT

Parent topic: JCLGN Error Messages


JCLGN0009U MISSING SYSIN

Parent topic: JCLGN Error Messages


JCLGN0010U INVALID SYSIN

Parent topic: JCLGN Error Messages


JCLGN0011U I/O ERROR ON SYSPRINT

Parent topic: JCLGN Error Messages


JCLGN0012U I/O ERROR ON SYSIN

Parent topic: JCLGN Error Messages


JCLGN0100U MISSING DD STATEMENT FOR filename

You have referenced a data set from a program but your JCL does not include a DD entry for it.
Parent topic: JCLGN Error Messages


JCLGN0101U INVALID DSORG FOR filename

The data set's DSORG is inappropriate for the operation you are trying to perform.
Parent topic: JCLGN Error Messages


JCLGN0102U I/O ERROR ON filename

Parent topic: JCLGN Error Messages


JCLGN0103U I/O STATUS = file status

Parent topic: JCLGN Error Messages


JCLGN0104U MFJGENER ABENDED system code

See preceding messages for details of the error.
Parent topic: JCLGN Error Messages


JCLGN0110I number RECORDS COPIED FROM SYSUT1 TO SYSUT2

Parent topic: JCLGN Error Messages


JCLGN0111I number RECORDS COPIED

Parent topic: JCLGN Error Messages


JCLGN0112I TO MEMBER NAME %

Parent topic: JCLGN Error Messages


JCLGN0200E PARAMETER TOO LONG [value]

Parent topic: JCLGN Error Messages


JCLGN0201E CONTINUATION ERROR [value]

Parent topic: JCLGN Error Messages


JCLGN0202E MISMATCHED QUOTES OR PARENTHESIS [value]

Parent topic: JCLGN Error Messages


JCLGN0210E UNRECOGNIZED OPERATOR KEYWORD [value]

Parent topic: JCLGN Error Messages


JCLGN0211E DUPLICATE CONTROL STATEMENT [value]

Parent topic: JCLGN Error Messages


JCLGN0220E UNRECOGNIZED OPERAND KEYWORD [value]

Parent topic: JCLGN Error Messages


JCLGN0221E DUPLICATE OPERAND KEYWORD [value]

Parent topic: JCLGN Error Messages


JCLGN0222E TOO MANY OPERANDS [value]

Parent topic: JCLGN Error Messages


JCLGN0223E INVALID OPERAND VALUE [restriction]

The restriction shows the values permitted.
Parent topic: JCLGN Error Messages


JCLGN0224E UNEXPECTED OPERAND [%]

Too many operands are present.
Parent topic: JCLGN Error Messages


JCLGN0225E EXPECTED OPERAND MISSING [parameter]

A required operand is missing from parameter.
Parent topic: JCLGN Error Messages


JCLIM0201U MISSING DDITV02 DD STATEMENT

Parent topic: JCLIM Error Messages


JCLIM0202U INVALID DDITV02 PARM STATEMENT

Parent topic: JCLIM Error Messages


JCLIM0203U INVALID DDITV02 PROGRAM PARM

Parent topic: JCLIM Error Messages


JCLIM0204U I/O ERROR ON DDITV02 DATASET

Parent topic: JCLIM Error Messages


JCLUT0100S MISSING "filename"

The file cannot be found
Parent topic: JCLUT Error Messages


JCLUT0101S INVALID "filename"

Message

Invalid "%1$s"

Where %1$s is filename.

Message Information

The file attributes are invalid.

Resolution

Correct the file properties so that the operation is valid.

Parent topic: JCLUT Error Messages


JCLUT0102S I/O ERROR ON "PDS member name"

The PDS member does not exist or is invalid.
Parent topic: JCLUT Error Messages


JCLUT0103S UTILITY "utility-name" ABENDED

An error has caused the utility to abend.

Resolution:

Check preceding messages for the reason.

Parent topic: JCLUT Error Messages


JCLUT0104S DUPLICATE MEMBER "PDS-member-name"

You have tried to create a PDS member but a member with that name already exists.

Resolution:

Use a different name.

Parent topic: JCLUT Error Messages


JCLUT0105S CATALOG ERROR ON "dataset-name"

Message

Catalog error on %1$s

Where %1$s is Dataset name.

Message Information

Either you have referenced a data set that has no entry in the catalog, or you have tried to catalog a data set with a name that already exists in the catalog.

Resolution

Check the catalog entry for this dataset.

Parent topic: JCLUT Error Messages


JCLUT0106S RETURN CODE IS "value"

Message

Return code is "%1$s"

Where %1$s is return code.

Message Information

The value of the return code is not as expected.

Parent topic: JCLUT Error Messages


JCLUT0201I MEMBER "PDS-member-name" NOT FOUND

You have tried to access a PDS member but there is no catalog entry for it.
Parent topic: JCLUT Error Messages


JCLUT0202I RECORDS COPIED "number"

Message

Records copied "%1$s"

Where %1$s is Number of records.

Message Information

The number of records copied.

Resolution

No action is required.

Parent topic: JCLUT Error Messages


JCLUT0203I MEMBERS NAME "PDS-member-name"

Message

Members name "%1$s".

Where %1$s is PDS member name.

Message Information

The name of the PDS member.

Resolution

No action is required.

Parent topic: JCLUT Error Messages


JCLUT0204I MEMBERS WRITTEN TO OUTPUT DD "number"

Message

Members written to output DD "%1$s".

Where %1$s is the number of members.

Message Information

The number of members written to output DD.

Resolution

No action is required.

Parent topic: JCLUT Error Messages


JCLUT0205I INDD=OUTDD="filename", COMPRESS IN PLACE IGNORED

Message

INDD=OUTDD="%1$s", compress in place ignored.

Where %1$s is Dataset name.

Message Information

Informational only. "Compress in place" is not meaningful on the PC, so control statements requesting it are ignored.

Resolution:

No action is required.

Parent topic: JCLUT Error Messages


JCLUT0206S Character set mismatch. Copied without conversion

Message

Character set mismatch. Copied without conversion

Message Information

You are trying to copy an ASCII dataset to an EBCDIC one, or vice versa.

Resolution

Convert one of the datasets so that both match.

Parent topic: JCLUT Error Messages


JCLCM0165S Open for joblog "filename" failed. Also see JCLCM0166

Use the extended file status code for more information on this failure.

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: JCLCM0000 - JCLCM0199
Related concepts
Run-time System Error Messages


JCLCM0166S File status code for last file I/O failure was value

Use the extended file status code for more information on this failure.

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: JCLCM0000 - JCLCM0199
Related concepts
Run-time System Error Messages


JCLCM0094I Non-JCL record in the input stream has caused this SYSIN DD statement to be generated.

This message, while it never appears in any JCL listings, is referred to in the generated SYSIN DD statement. It means that in your JCL source stream, you have one or more non-JCL records before the final // if any.

Example of non-JCL records

//MYJOB JOB
//STEP1 EXEC PGM=IEFBR14
//SYSOUT DD SYSOUT=*
   some data
   some more data
//SYSPRINT DD SYSOUT=*
blank line
//

The above JCL will cause two statements of the form:

//SYSIN DD * ***MFE JCL GENERATED STMT*** For more info, see JCLCM0094I

to appear, one after /SYSOUT DD and the other after //SYSPRINT DD.

Parent topic: JCLCM0000 - JCLCM0199


JCLCM0218S System error "internal code"

System error.

Resolution:

Contact SupportLine. Please mention the internal code.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0600E - PORTNO "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0601E - PRMODE "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0602E - PRTERROR "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0603E - PRTOPTNS "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0604E - PRTQUEUE "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0605E - PRTY "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0606E - RESFMT "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0607E - RETAINS/RETAINF "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0608E - RETRYL/RETRYT "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0609E - ROOM "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0610E - SYSAREA "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0611E - THRESHLD "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0612E - TITLE "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0613E - TRC "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0614E - UCS "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0615E - USERDATA "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0616E - USERLIB "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0617E - WRITER "nn" parameter has invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0618E - Excess operand(s) starting with "nn" are ignored

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0619E - LSEQRECF parameter "nn" is invalid

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0620E - RESTART parameter "nn" is invalid

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0621E - HOSTJOB parameter "nn" is invalid

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0622U - System error writing nn file. Contact Micro Focus

An error occurred while writing to one of the lexigraphical files.

Lexigraphical files contain the parsed JCL and have file names of the format MFE2014.S0717.S140415.J00101.MFELX*.DAT, where * can be either a number or letter. Such files might be of zero length.

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0623E - SUBSYS parameter "nn" is longer than 2698 bytes

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0624E - JESLOG parameter has an invalid value

Parent topic: JCLCM0600 - JCLCM0699


JCLIM0005U - Program Parm Contains Invalid Character n

Parent topic: JCLIM Error Messages


JCLIM0205U - Missing DD Statement nnnnnn

Parent topic: JCLIM Error Messages


JCLIM0206U - Invalid Dsorg For n

Parent topic: JCLIM Error Messages


JCLIM0207U - Invalid/Missing Control Statement On n

Parent topic: JCLIM Error Messages


JCLIM0208U - I/O Error On n

Parent topic: JCLIM Error Messages


Select the mainframe systems being used

JES/2 | Select this if you are using a JES/2 spool system on your mainframe.
JES/3 | Select this if you are using a JES/3 spool system on your mainframe.
CA Librarian | Select this if you are using Computer Associates Librarian on your mainframe.
CA Panvalet | Select this if you are using Computer Associates Panvalet on your mainframe.
CA Endevor | Select this if you are using Computer Associates Endevor on your mainframe.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Librarian options

Name of Librarian executable In order for MFA to add or replace members into Librarian, it must invoke the specified Librarian module. If your installation has changed the name of this module, or you wish to have MFA call a different one, then alter the name of the module.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Panvalet options

Name of Panvalet executable | In order for MFA to add or replace members into Panvalet, it must invoke the specified Panvalet module. If your installation has changed the name of this module, or you wish to have MFA call a different one, then alter the name of the module.
Data type | When MFA add a new member of type data, it will use the specified value to inform Panvalet about the member type.
COBOL type | When MFA add a new member of type data, it will use the specified value to inform Panvalet about the member type.
PL/I type | When MFA add a new member of type data, it will use the specified value to inform Panvalet about the member type.
BAL type | When MFA add a new member of type data, it will use the specified value to inform Panvalet about the member type.
JCL type | When MFA add a new member of type data, it will use the specified value to inform Panvalet about the member type.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Select the communications methods for the server

TCP/IP DirectConnect | Select DirectConnect if you are wish to access the mainframe directly from the workstation using a static pre-defined IP port. This is the preferred method of connection, as it does not require a long-running daemon on a workstation somewhere. You may have both DirectConnect and DaemonConnect if desired.
TCP/IP DaemonConnect | Select DaemonConnect if you wish to access the mainframe indirectly from the workstation using a variable unknown IP port. This method will require a long-running CCITCP2 daemon to be started on a workstation located somewhere in the network. You may have both DirectConnect and DaemonConnect if desired.
VTAM | Select VTAM if you wish to access the mainframe server through an APPC connection. This will require a 3rd party APPC stack to be installed on each workstation.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Select the TCP/IP method for the server

Select the TCP/IP communication stack and release level in effect at your installation.

Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify the name of the MFA standard server

Name of standard MFA server This is the name given to the JCL member which is used to execute the MFA standard server. This JCL is placed into a system procedure library so it can be used by the MVS console operator to start the server procedure.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify the DirectConnect details for the standard server

Name of TCP/IP started mainframe task | This is the name specified when TCP/IP support for the IBM mainframe is started.
Permanent TCP/IP port number for MFA | DirectConnect support requires a non-changing assigned port number to listen to. Your TCP/IP administrator can tell you a specific number to use. This is the value that is used by the workstation clients in the MFNODE:ipaddress,MFPORT:port configuration parameter.
Mainframe TCP/IP address to bind with | (Optional) This is the TCP/IP address that you wish to have the mainframe bind with. Normally, the first IP address on the HOST statement in the TCP/IP mainframe configuration is used, but if this is not the correct address, or if the primary adapter statement is not set to the same ring, then you must force the mainframe server to use a specific IP address. A TCP/IP address takes the formnnn.nnn.nnn.nnn where nnn has a value from 001 to 255. The periods separating the IP address segments are not entered on the screen.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify the DaemonConnect details for the standard server

Name of TCP/IP started mainframe task | This is the name specified when TCP/IP support for the IBM mainframe is started.
Name this server is to be known by | DaemonConnect support requires a non-changing name to be assigned to the server. This is the name that is used by the workstation clients in the configuration server name.
Workstation TCP/IP address of daemon | This is the TCP/IP address of the long-running workstation CCITCP2 daemon process, that you wish to have the mainframe bind with. A TCP/IP address takes the formnnn.nnn.nnn.nnn where nnn has a value from 001 to 255. The periods separating the IP address segments are not entered on the screen.
Mainframe TCP/IP address to bind with | (Optional) This is the TCP/IP address that you wish to have the mainframe bind with. Normally, the first IP address on the HOST statement in the TCP/IP mainframe configuration is used, but if this is not the correct address, or if the primary adapter statement is not set to the same ring, then you must force the mainframe server to use a specific IP address. A TCP/IP address takes the formnnn.nnn.nnn.nnn where nnn has a value from 001 to 255. The periods separating the IP address segments are not entered on the screen.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify the name of the MFA standard server VTAM APPLID

Name of standard MFA server VTAM APPLID This is the VTAM application name associated with this server. When configuring communications on the workstation this item is also known as the Partner LU.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify the name of the MFA standard load library

Name of MFA standard loadlib | This is the dataset name of the PDS load library for the MVS servers. This library contains the run time executable programs and must be APF authorized.
Name of RLIO VCTL library | This is the name of the PDS library which will be used to contain dataset allocation information for new datasets, for DataConnect.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify the TCP/IP library name

TCP library containing EZACICAL This is the name of the TCP/IP library which contains the module EZACICAL. The EZACICAL module is link-edited with the TCP/IP server at installation time.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify the name of the mainframe volume for IDCAMS defines

Name of mainframe volume This is the name of a permanent mainframe volume that will be used to define a few VSAM cluster on for use by the MFA server.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify the name of the MFA Endevor load libraries

Name of Endevor loadlib | This is the name of your current Endevor system's load library.
Name of Endevor conlib | This is the name of your current Endevor system's CONLIB library. If you do not use a CONLIB, then specify the Endevor loadlib again.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify the names of the MFA Endevor support work files

Name of SYS080 work file | This is the dataset name that will be used to allocate and utilize the required SYS080 work file.
Name of SYS160 work file | This is the dataset name that will be used to allocate and utilize the required SYS160 work file.
Name of MSG001 work file | This is the dataset name that will be used to allocate and utilize the required MSG001 work file.
Note: If any of the dataset names specified in this dialog box already exist, you must either delete them or edit their names before continuing. Failure to do so will result in the imcomplete installation of MFA. These datasets will exist if you have previously installed this version of MFA, or have installed MFA Version 2.01 with PTF4.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify the Endevor system to store control modules

Name of Endevor environment | MFA must create modules to be placed into your Endevor system. Specify the environment to be used, and this must be available at run-time for this server.
Name of Endevor system | MFA must create modules to be placed into your Endevor system. Specify the system to be used, and this must be available at run-time for this server.
Name of Endevor subsystem | MFA must create modules to be placed into your Endevor system. Specify the subsystem to be used, and this must be available at run-time for this server.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Select the upload method for the server files

Upload using an existing MFA server | Good news, if you already have MFA running and are simply installing a new release, or an additional server, then you can take advantage of the power of MFA. By selecting this method, the installation program can automatically allocate new datasets, determine your environment, upload the modules and even submit the generated JCL.
Upload using an external manual method | If MFA is not yet installed on your system, then select this method, and the JCL streams will be generated for you. Instructions will also be provided, on what files are to be transferred, to where, and whether they are binary or text.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify the current MFA server details

User identification | Specify the user identification to be used for this software installation. Make sure that this userid has the appropriate dataset authorization.
Password | Specify the password associated with the userid given.
Current MFA server name | (Optional) Specify the name of the standard mainframe server, as known to the CCI daemon. If you are not using the CCI daemon, and using direct connect TCP/IP instead, then specify the name of the started mainframe task.
Current MFA machine parms | (Optional) Specify the machine parameters of any current MFA server that is running. If you are using APPC, or direct connect TCP/IP then you will need to enter information here. For APPC, you would most likely enter the LUname.mode, for example WKSLU010.#INTER where WKSLU010 is your LU name. For TCP/IP direct connect, you would enter MFNODE:xxx.xxx.xxx.xxx,MFPORT:yyyy where xxx.xxx.xxx.xxx would be the IP address, or DNS name of your mainframe, and yyyy would be the assigned TCP/IP port that the standard mainframe server is to listen on. To determine these values, you may refer to the $MFATCP member in the mainframe INSTLIB dataset.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Instructions on manually uploading mainframe files

Notes located in Detailed notes on completing the installation process have been generated and are located in the C:\MicroFocusMFA directory, under the file name NOTES. This file will be displayed using Notepad once the setup program has been finished. Follow these notes to complete the installation.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Mainframe processing to be completed

Installation dataset The name of the mainframe installation dataset is given. Detailed notes on completing the installation process have been generated and are located in the C:\MicroFocusMFA directory, under the file name NOTES. This file will be displayed using Notepad once the setup program has been finished. Follow these notes to complete the installation.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Select how the PTF pack is to be obtained

Access the Micro Focus ftp site and download the PTF pack | Select this process if you have Internet access to the outside world. The maintenance process will automatically access the correct ftp site, determine the highest PTF package level available for your server, and download the PTF package to the C:\MicroFocusMFA directory. Make sure that you have at least 10 megabytes of free disk space on your C drive.
I have already downloaded the PTF pack to C:\MicroFocusMFA | Select this process if you do not have Internet access to the outside world. You will need to access the Micro Focus ftp site (ftp://ftp.microfocus.com/middleware/mfa/) and download to the C:\MicroFocusMFA directory, the highest level PTF package. Make sure that you have at least 10 megabytes of free disk space on your C drive.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Select the mainframe servers to update

Update MFA Standard server Select this if you want to update the base level MFA server with a PTF. This server is used by all Drag and Drop clients, all Compare and Synchronize clients, and all SourceConnect and DataConnect clients.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Verify the dataset names in use

Name of installation library | The name of this library is remembered from the server installation process, but if for some reason it has been changed, then alter the name here.
Name of standard object library | (Optional) The name of this library is remembered from the server installation process, but if for some reason it has been changed, then alter the name here.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Verify the dataset names in use

Name of standard load library The name of this library is remembered from the server installation process, but if for some reason it has been changed, then alter the name here.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Workstation update is now complete

You have successfully completed the update to your workstation of the MFA PTF package.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Registration is now complete

You have successfully registered with Micro Focus to be notified for future updates.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Enter the required Endevor profile information

Type | Specify the Endevor member type for this member.
CCID | Specify any required change control identification for this member.
Comment | Specify any required comment for this member.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Enter the required Endevor profile information

Type | Specify the Endevor member type for this member.
CCID | Specify any required change control identification for this member.
Comment | Specify any required comment for this member.
Signout member | If you wish to have the member automatically signed out, then select this option.
Override existing signout | If you wish to override any existing signout for this member, then select this option.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Enter the required Endevor profile information

Type | Specify the Endevor member type for this member.
CCID | Specify any required change control identification for this member.
Comment | Specify any required comment for this member.
Override existing signout | If you wish to override any existing signout for this member, then select this option.
Bypass generate processor | If you wish to bypass any mainframe generation, then select this option.
Env | Specify the environment to be used for this update.
Sys | Specify the system to be used for this update.
Sub | Specify the subsystem to be used for this update.
Stg | Specify the stage to be used for this update.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Copy statements detected

Select the copy members you wish to have located and downloaded | You have been presented with a list of detected copy members. If you wish to import any of the members from the list, select one or more of them using the standard selection keys or mouse clicks. The copy file pattern matching algorithm tries to locate the proper copy file names, but since it is not a compiler, it will sometime pick up names that are not really copy files.
Search one or more mainframe dataset, each delimited by comma | This field allows you to specify the list of mainframe datasets, or source code control system libraries to search in. If the member is not found in the first dataset, then and only then is the next checked for the member.
Write copy members to directory or Mainframe Express dataset | This field allows you to alter the location that the copy members are to be stored into. You may also specify a Mainframe Express partitioned dataset.
Write members with extension | This field allows you to set or alter the file extension that the copy members are to be stored as.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Enter the required VSAM record selection criteria

Download all records | Select this option if all of the mainframe records are to be retrieved for the download.
Download record by low/high key range | Select this option if you wish to select records within a range. You may specify the lower key to select a starting range, or the upper key to select an ending range, or both keys for a lower and upper range. The data entered in this field is not converted to upper case. In addition, you may specify hexadecimal data in either of these fields by specifying hex bytes within X' ', such as X'C140C2E7F0'. Greater than and equal searches are done for the lower key, and less than or equal searches are done for the upper key.
Limit record count to the first | Select this option if the first N records are to be downloaded from the file.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Enter the required QSAM/VSAM record selection criteria

Download all records | Select this option if all of the mainframe records are to be retrieved for the download.
Limit record count to the first | Select this option if the first N records are to be downloaded from the file.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Enter the required IMS conversion information

Database name | This field specifies the name of the PCIMS database to load.
Location of segment name in data record | This field defines the offset in the unloaded database sequential file layout that the reload utility is to find the starting byte of the segment name. This field is relative to 1.
Location of segment data in data record | This field defines the offset in the unloaded database sequential file layout that the reload utility is to find the starting byte of the segment data. This field is relative to 1.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Enter the required DB2 conversion information

Location | This field specifies the name of the location containing the target table. If not specified, then the default location is used. You must use the mainframe DSNTIAUL utility to create the source data file.
Authid | This field specifies the authorization identifier of the table.
Table name | This field specifies the name of the table to be replaced.
EBCDIC code page | This field defines the mainframe code page in use.
ASCII code page | This field defines the workstation code page in use.
Page size | This field defines whether you wish to use a 4K or 32K page.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Enter the required information

Specify the name of the subdirectory to be created.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Enter the required information

Specify the new name of the member.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Enter the required information

Alter the name, if desired, that the file is to be pasted as.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Enter the required information

Specify the member subsetting to be performed. You may specify a specific member name, or use filter characters to be creative about a collection of members to be displayed. The filter characters are embedded with any other characters for pattern matching of the member name, similar to the usage of the wildcard characters on the workstation directory command. The filter characters are:
* | any character may follow
? | any character in this position
+ | the character in this position must be non-blank
- | the character in this position must be a blank
/ | the character in this position must be numeric
\ | the character in this position must be non-numeric
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Enter the required information

Specify the member type subsetting to be performed. You may specify a specific member type, or use filter characters to be creative about a collection of member types to be displayed. The filter characters are embedded with any other characters for pattern matching of the member type, similar to the usage of the wildcard characters on the workstation directory command. The filter characters are:
* | any character may follow
? | any character in this position
+ | the character in this position must be non-blank
- | the character in this position must be a blank
/ | the character in this position must be numeric
\ | the character in this position must be non-numeric
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Enter the required information

Specify the extension this dataset is to be associated with.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Enter the required information

Specify the directory subsetting to be performed. You may specify a specific file, or use filter characters to be creative about a collection of files and extensions to be displayed. The filter characters are embedded with any other characters for pattern matching of the file or extension, identical to the usage of the wildcard characters on the workstation directory command. The filter characters are:
* | any character may follow
? | any character in this position
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Enter the required information

Specify the extension this file is to be written with.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Enter the required information

Specify the file name and optional extension this dataset is to be written as.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Enter the required information

Specify the model for the new partitioned data set.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Enter the required information

Specify the model for the new sequential or VSAM data set.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Drag and Drop Utility General information

The Micro Focus Data Access Services File Transfer Utility (commonly known as Drag and Drop) provides a powerful drag-and-drop style GUI access to mainframe datasets, including support for the following data types:

  • Sequential (QSAM)
  • Partitioned (BPAM)
  • Librarian
  • Panvalet
  • Endevor
  • Keyed (VSAM KSDS)
  • Entry (VSAM ESDS)
  • Relative (VSAM RRDS)
  • JES system

You may drag files, individual members, or entire sets of members from the mainframe to the workstation, or back again. When importing from the mainframe, support for all file types is provided. When exporting from the workstation, support for most file types is available. In order for you to use this utility, the Mainframe Access Product must be purchased and successfully installed on your mainframe system.

Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Drag and Drop Utility Overview

The utility provides two scalable windows on the desktop. The left hand window provides a list of the workstation drives, directories and files. To expand a drive or directory, double click on the desired name. To contract an expanded drive or directory, double click again on the desired name. To browse a specific file, double click on the desired name. The field icon may be used in place of the right mouse context button. You may reposition a member list by using any alphabetic key. The right hand window provides a list of the mainframe datasets that are related to the catalog search criteria, asked for during the configuration options at initial start-up. The utility attempts to determine the dataset type, but certain files are impossible to determine. To inform the utility of the dataset type, single click on the right hand mouse button over the desired dataset to view the context menu. You may select the appropriate dataset type from the list. The utility will store this selection so that you do not have to repeat this process for this dataset. To expand a partitioned, Librarian, Panvalet, Endevor, or JES spool double click on the desired dataset. To contract an expanded dataset, double click again on the desired dataset. To browse a specific dataset or member, double click on the desired name. The drag and drop utility supports multiple selection as well as single selection for its actions. This works in the same way as other utilities available with the operating system. If you select an item by single-clicking on it without having either the Ctrl or Shift key depressed, then only that item will be selected and any other selected items in the same window will be de-selected for you. If you select an item by single-clicking on it and have the Ctrl key depressed, then the item selected will join any other selected items in the same window. If you select an item by single-clicking on it and have the Shift key depressed, then all items in the range of the last non-Shift selection to this line item will be selected. To copy a dataset, file or member from one platform to the other, you must: hold down the left mouse button over a desired dataset or file drag it over to the opposite window position the mouse over the desired target location release the mouse You may drag entire mainframe partitioned, Librarian, Panvalet or Endevor datasets, if you wish to copy all members to the workstation, or simply drag an individual file, or member if you wish to copy them one at a time. Likewise, the same can be done with workstation directories and files that are to be copied to the mainframe. All VSAM datasets, when copied from the mainframe to the workstation, are automatically converted to the appropriate workstation file format. For these files, however, the EBCDIC to ASCII conversion is not performed. You must use the Micro Focus Data File Convertor Utility (DFCONV) on your own.

Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Hints


Drag and Drop Utility Hints

The high performance Data Access Services is a drag and drop style utility. To copy files to and from the mainframe, simply single-click on the desired file names, and drag them to the required location in the opposite window. Entire directories or datasets, containing multiple files can be dragged, if desired. To set global options, use the Options action in the Configure pull-down. To set specific types for mainframe datasets, use the right mouse context button over the desired mainframe dataset name. To expand the drive, directory, or mainframe dataset, and produce a member list, double-click on the desired item. To contract these expanded lists, double-click once again. To display a limited number of lines of a workstation file or a mainframe dataset or member, double-click on the desired item to produce a browse window. The browse limit can be altered by using the Options action. The drag and drop utility supports multiple selection as well as single selection for its actions. This works in the same way as other utilities available with the operating system. If you select an item by single-clicking on it without having either the Ctrl or Shift key depressed, then only that item will be selected and any other selected items in the same window will be de-selected for you. If you select an item by single-clicking on it and have the Ctrl key depressed, then the item selected will join any other selected items in the same window. If you select an item by single-clicking on it and have the Shift key depressed, then all items in the range of the last non-Shift selection to this line item will be selected. You may dynamically alter the mainframe list of datasets by changing the 'Catalog search criteria' field by using the 'Options' action under the 'File' pull-down. You may dynamically alter the mainframe Endevor qualification by changing the 'Endevor qualification' field by using the 'Options' action under the 'File' pull-down.

Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview


Log on to the mainframe

User identification | Specify the user identification to be used for this application. Make sure that this userid has the appropriate dataset authorization.
Current Password | Specify the password associated with the userid given.
CCI Communication Type | Select either TCP/IP or VTAM's APPC as your communication method. You must make sure that the appropriate communication stack has been installed.
Standard Server Name | (Optional) Specify the name of the standard mainframe server, as known to the CCI daemon. If you are not using the CCI daemon, and using direct connect TCP/IP instead, then specify the name of the started mainframe task.
Standard Server IP node and Port | (Optional) Specify the machine parameters of any current MFA server that is running. If you are using direct connect TCP/IP then you will need to enter information here. You would enter either the DNS name of your mainframe, or the IP address in the form xxx.xxx.xxx.xxx for the IP node, and the assigned port number of the MFA server in the form yyyy for the port. To determine these values, you may refer to the $MFATCP member in the mainframe INSTLIB dataset.
Standard Server LU name and Mode | Specify the LU name and mode to be used with this APPC connection. Typically, #INTER is the usual mode to be used.
Endevor Server Name | (Optional) Specify the name of the Endevor support mainframe server, as known to the CCI daemon. If you are not using the CCI daemon, and using direct connect TCP/IP instead, then specify the name of the started mainframe task.
Endevor Server IP node and Port | (Optional) Specify the machine parameters of any current MFA server that is running. If you are using direct connect TCP/IP then you will need to enter information here. You would enter either the DNS name of your mainframe, or the IP address in the form xxx.xxx.xxx.xxx for the IP node, and the assigned port number of the MFA server in the form yyyy for the port. To determine these values, you may refer to the $MFATCP member in the mainframe INSTLIB dataset.
Endevor Server LU name and Mode | Specify the LU name and mode to be used with this APPC connection. Typically, #INTER is the usual mode to be used.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints


Configuration

Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Configure options

Title | The text to be used on the application task bar. This enables you to easily identify a specific monitor session from the task list.
Startup | This time you want the monitor to start up. This is generally used in conjunction with the wakeup option. If used, the format is in 24 hour time, and must be in the range of 00:00 to 23:59.
Wakeup | The length of time the monitor should remain dormant after the initial analysis has completed but before analyzing the environment for subsequent changes to be processed. The default is to remain dormant for 8 hours.
Perform this many monitor iterations before shutting down | The number of times the monitor is to do the analysis scan. The default is forever, but if you wish to invoke this process a limited number of times, then specify a value.
Allow a maximum of this many transfers in an iteration | The maximum number of imports or exports the monitor does per cycle. The default is to transfer all required files.
Clean up mainframe connection after this many transfers | The number of mainframe server requests to make before the monitor automatically terminates the connection to the mainframe and then initiate a new connection. Some mainframe source code control systems and operating system functions allocate mainframe memory which is not freed by the routines called by the MFA server subtasks. This memory tends to accumulate and make the MFA server's memory usage increase. By setting a value to cause this automatic termination and re-connection, this so-called dead memory, tends to get freed up. Generally, disconnections and connections are fairly fast, so a reasonable value for this parameter is about 500.
Delete workstation file if mainframe member is deleted | When checked, the monitor deletes workstation files when it notices that the corresponding mainframe member has been deleted. This is especially useful in environments that do promotions of mainframe members to higher level datasets, and want to mirror this promotion on the workstation. The default is to ignore this situation and not delete the workstation files. When checked, the monitor also deletes workstation files that were placed in the target directory by a process other that the synchronization process. This deletion only occurs if this option is checked, the mainframe file is deleted, and the direction of the synchronization is down to the PC only.
Handle embedded hex in the Micro Focus MDECONV format | When checked, all source code embedded hex values are handled in the same way as the Workbench MDECONV application, in that all translated hex values less than x'20' will have a null character inserted before the hex value. The COBOL run-time system will properly handle these embedded hex values. Revolve users may or may not want to turn on this option.
Suppress embedded hex warning messages | When checked, suppresses the hex character in downloaded file warning messages.
Monitor the following | A list of workstation/dataset monitor relationships is provided. Use the Add button to add a new relationship, the Remove button to delete a selected relationship, or the Configure button to alter a selected relationship.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify the directions to monitor

Monitor for both upload and download | Monitor, and allow both uploads and downloads to occur.
Monitor for upload to the mainframe only | Monitor, but do not allow a download to occur. This will allow upload synchronization to occur.
Monitor for download to the workstation only | Monitor, but do not allow an upload to occur. This will allow download synchronization to occur.
Monitor, but do not upload or download | Monitor, but do not allow an upload or download to occur. This will produce a report only.
Disable EBCDIC/ASCII translation (binary transfer) | Check this to specify that you do not want EBCDIC/ASCII translation to occur. This option is useful if you have a PDS containing binary data, and is only available if you have selected a PDS to be monitored.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints


Specify any member subsetting to be done

Use Advanced Filter Method | Check this to make the monitor use the advanced filtering system. If the box is left unchecked then the old filter expression method will be used.
Old filter method expression | You may specify a specific member name, or use filter characters to be creative about a collection of members to be monitored. The filter characters are embedded with any other characters for pattern matching of the member name, similar to the usage of the wildcard characters on the workstation directory command. The filter characters are:
* any character may follow
? any character in this position
+ the character in this position must be non-blank
- the character in this position must be a blank
/ the character in this position must be numeric
\ the character in this position must be non-numeric
Advanced filter method When the advanced filter method checkbox is checked, the Current Active Filter list box, and the Filter Database list box become active. To add rules to the current active filters, select it in the filter database list box, and click on either the Include button, or the Exclude button that become active between the two list boxes. Clicking on the Include button adds the filter rule to the active filters as an Include filter. This means that any files passed by the filter will be included in the file processing between the host and PC and vice versa. Clicking on the Exclude button adds the filter rule to the active filters as an Exclude filter. This means that any files passed by the filter will be Excluded from the file processing between the host and PC and vice versa.

In the screenshot above, when the filters are applied to the synchronisation process, any files found by the HIGHCHARACTER rule will be excluded, and anything found by the EVERYTHING rule will be included.

NB, an exclude rule will always take precedence over any include rule. So although everything is requested in the EVERYTHING rule, the files excluded by the HIGHCHARACTER rule will be excluded.

The rules database is maintained from the "Configure advanced filter database" menu item under the Configure option on the main menu. Please refer to the help availabe there for more information on building advanced filter rules.

Remove | Select an item in the Current Active Filter list box, and then click the remove button to remove it from the list.
Toggle | Select an item in the Current Active Filter list box, and then click the Toggle button to toggle it between include processing and exclude processing.
Old Filter Method If the Use Advanced Filter Method checkbox is not checked, then the following filter rule applies :

You can specify a specific member name, or use filter characters to be creative about a collection of members to be monitored. The filter characters are embedded with any other characters for pattern matching of the member name, similar to the usage of the wildcard characters on the workstation directory command. The filter characters are:

* any character may follow
? any character in this position
+ the character in this position must be non-blank
- the character in this position must be a blank
/ the character in this position must be numeric
\ the character in this position must be non-numeric
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints


Specify the workstation location

Location of workstation directory | You must specify the fully qualified location of a workstation directory to complete the monitor relationship. This is the name of the directory without any additional characters such as *.CBL. You may use the browse button to aid in the location of the directory.
Location of PVCS archive | You must specify the fully qualified location of a PVCS archive CFG file to complete the monitor relationship. This is the name of the archive with the usual ARCHIVENAME.CFG at the end. You may use the browse button to aid in the location of the archive file.
Extension | You must specify the specific extension, such as all CBL files in the directory, to be monitored against, or written as. If you specify the extension as three asterisks (***), the download initially downloads the file with no extension. If the file extension is then changed, the next synchronization operation finds the first matching filename with any extension. Only one file with the same filename can exist in the target directory. For example, if a host PDS member name is ACCTOPEN and no file with the prefix ACCTOPEN exists in the PC target directory, the file is downloaded as ACCTOPEN. If the extension is then modified to ACCTOPEN.CBL, the next synchronization detects the target filename as ACCTOPEN.CBL and synchronizes against that.
Monitor against | Select whether you are monitoring against a directory of standard files, or a PVCS archive.
Optional version label | If you are monitoring against PVCS, then you may monitor against a specific version label, if desired.
Optional promotion group | If you are monitoring against PVCS, then you may monitor against a specific promotion group, if desired.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints


Compare and Synchronize Monitor General Information

The Compare and Synchronize Monitor allows users to interrogate both workstation and mainframe source code and data files, and determine if any changes have occurred. If changes have occurred, then the user through configuration information, instructs the Monitor on the automatic action to be taken, such as downloading or uploading the change files. This enables an environment to be set up that allows a user to mirror workstation and mainframe files, and to automatically transport all changes to the mirrored counterpart.

Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints
Advanced filter details.


Compare and Synchronize Monitor Overview

To use the Compare and Synchronize Monitor, the user must perform a configuration. This is done in the MFMONMX program by using the Configure Options pull-down. This pull-down invoked the GUI configuration utility where the user instructs the Monitor on the workstation locations and mainframe datasets to be mirrored.

Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Hints
Advanced filter details.


Compare and Synchronize Monitor Hints

The Compare and Synchronize Monitor is useful for creating a local workstation directory that is identical to the mainframe datasets. This is helpful when using other products such as Mainframe Express, or Revolve, as the access to the workstation files is always faster than going over a communications link to any mainframe.

Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Advanced filter details.
Compare and Synchronize Monitor Hints


Enter the required information

Specify the pattern to be used for pre- and post-download member filtering.

Pre-download member filtering consists of simple expressions, using the PC-style wildcard characters below.

Post-download member filtering can also use regular expressions when the Use Regular Expressions option is checked.

* | any character may follow
? | any character in this position
+ | the character in this position must be non-blank
- | the character in this position must be a blank
/ | the character in this position must be numeric
\ | the character in this position must be non-numeric
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Select the desired setup procedure

Install MFA base product mainframe software | Select this procedure if you are installing the mainframe MFA server for either the first time, installing additional MFA servers, or installing a higher level replacement MFA server.
Update your MFA clients/servers with a PTF package | Select this procedure if you are wanting to automatically apply maintenance to your current MFA clients and servers. It is highly recommended that you install the client software in a common LAN-based directory, so that the update will replace the executables shared by all users.
Upgrade the concurrent number of users limit to a higher level | Select this procedure if you have purchased a higher concurrent user limit and want to apply the higher limit to the mainframe servers.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify your e:mail identification

E:mail id If you wish to be automatically notified when PTF packages become available, then specify your e:mail id in this field. Once the Next button is pressed, your id will be sent to our ftp site, where it will be used for the master mailing list for MFA updates. If you wish to have more than one id placed on our ftp site, then specify the first id and press Next, then press Back on the next panel to return to this panel, where you can place another id to be registered.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify the general mainframe information

High level qualifier to use for DSN's | This is the prefix to all dataset names created during the installation of the server. The maximum length of this prefix is 35 characters. A period '.' and the library name are appended to the prefix to form the library dataset name. The prefix must conform to MVS dataset naming conventions.
DASD unit name | This is the symbolic name for the disk drives on which you will be creating the datasets as a result of the installation process. This must be a valid name for your installation.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Select the mainframe security system being used

IBM RACF | Select this security system if you are using IBM's RACF, or no security at all. If you wish to install the MFA server without security active, then after the installation has completed, edit the INSTLIB member $MVSSEC and follow the instructions for turning off security.
CA Top Secret | Select this security system if you are using Computer Associate's Top Secret. You must define the MFA server as a facility to Top Secret. Failure to do this will cause an outstanding reply to be required from the console for the MFA server, thus making it appear that the client application has hung.
CA ACF/2 | Select this security system if you are using Computer Associate's ACF/2. You must define the MFA server with privileges "JOB STC" to ACF/2.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify your valid JOB card information

Enter a valid job card. Each MFA jobstream will be generated using this job card information. You can copy and paste this job card from a 3270 emulator session if desired.

Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify the MFA activation codes

Concurrent users activation code This enablement code specifies the maximum number of users who can be logged on simultaneously. Each workstation application will issue a logon when the first file is opened and a logoff when the last file is closed. If two applications are running on the same workstation this will count as two concurrent users.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Select the mainframe servers to install

Install MFA Standard server Select this if you wish to install the base level MFA server. This server is used by all Drag and Drop clients, all Compare and Synchronize clients, and all SourceConnect and DataConnect clients.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Log on to the mainframe

User identification | Specify the user identification to be used for this application. Make sure that this userid has the appropriate dataset authorization.
Current | Specify the password associated with the userid given.
New | To change your mainframe password, enter the new one here and repeat it in the Repeat field.
Repeat | If you are changing your mainframe password, the new password must be entered the New field, and repeated in the Repeat field.
 | To have Drag and Drop automatically log you off the mainframe after a period in inactivity, enter the number of required minutes. Specifying zero will de-activate this feature.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Environment

Use codepage
The workstation code page that is used when performing ASCII to EBCDIC, and EBCDIC to ASCII translations, is sent to the mainframe during the initial connection. The default workstation code page may not be desired for non-North American workstations users. For example, if you require DBCS support, select one of the code pages now available that supports DBCS. The DBCS supported code pages are also available with various SOSI methods:
default (that is, with no method appended)
EBCIDIC SI/SO added on upload, removed on download
-SOSI-K
EBCIDIC SI/SO assumed on upload, preserved on download
-SOSI-A
ASCII SI/SO assumed on upload, preserved on download
-SOSI-S
Spaces converted to SI/SO on upload. SI/SO converted to spaces on download
Note: This will only work correctly with text that originates on a host.

To enable DBCS support, you must edit the started task JCL procedure; see MFA Started JCL Procedure for more information.

By setting the Use Codepage field to the proper code page, the associated code page is sent to the mainframe, instead of the workstation default one. By setting this field to mainframe default, no code page is sent from the workstation, but instead the default mainframe translate tables located in MFLSCTRN on the mainframe are used instead. The proper tables must have been selected during the mainframe installation of the server.

Limit browse lines to | This numeric field limits the number of lines that will be read and transferred when double clicking on a file or member. If you specify zero, there is no limit.
Default editor specification | You may specify the command and any optional parameters for a default editor to be used, when using the right mouse context button for the edit function. This default editor will be used, unless a Windows editor for the specific file extension has already been set up. You must fully qualify the editor command, include the path and extension of the program to invoke.
Add Command | Click this to add an editor to the Open with popup menu item (which is displayed when you right-click on a file). After clicking Add Command specify the editor's details in the Description, Command and Parameters fields, check Save Mainframe Edits? if appropriate, then click Save Commands.
Delete Command | Click this to delete the selected editor.
Save Commands | Click this to save the changes you have made to any editor definitions.
Reset All Commands | Click this to reset all editor commands to the default . After clicking this button (and clicking Yes on the subsequent confirmation message box), the only editor on the Open with popup menu item is Notepad. Any definitions you have added are lost.
Description | The name that will appear on the Open with menu item for an editor that you have defined. Specifying a single ampersand (&) causes an underscore to be displayed beneath the character following the ampersand, signaling a keyboard shortcut. To display an ampersand you need to specify two consecutive ampersands (&&).
Command | The command to run for the selected editor.
Parameters | The parameters to use on the command line for the selected editor. %s is used to denote the file that is to be edited.
Save Mainframe Edits? | Specifies whether the files changed by the selected editor are exported to the mainframe. This has no effect when using the editor on the PC side.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Options

EBCDIC/ASCII translation | Set this flag for each data set type that is to be translated to/from ASCII/EBCDIC.
Warn if the target name does not match the source | Set this flag if you want to be warned that dragging a file or member would result in the target file having a different name from the source file.
Warn if the target exists | Set this flag if you want to be warned when dragging a file or member if the file already exists. Note that there is an overhead when using this flag as the mainframe must be checked for the existence of the file or member.
Warn if the source files contain embedded hex | Set this flag if you want to be informed in an imported source file contains unusual or unprintable characters.
Use MDECONV style embedded hex processing | This method, when selected, will detect all embedded hex values that translate to less than x'20' and insert a null byte in front of each of them. This is the Micro Focus Workbench MDECONV technique, and all Micro Focus COBOL applications will properly detect this.
Inform when submitted jobs have completed | Set this flag if you wish to be informed when your submitted jobstream has finished.
Inform when migrated datasets have been recalled | Set this flag if you want to be informed when a dataset you have asked to be recalled has completed.
Prompt for an extension on import | Set this flag if you want to ensure that a dragged member will be written out with a PC extension.
Use Associated Extensions Set this flag to enable any extension that you have associated with data set members; these are applied when you import the members to your local system.

When enabled, any associations set via Drag and Drop will override any set via Source Connect.

Refresh mainframe member lists after subsetting | Set this flag if you want to force a refreshed member list after using the directory subsetting feature. There is a small overhead to this option.
files after transfer completes | Set this flag if after transferring VSAM files you want to delete the temporary files that were created during the transfer.
Suppress | Set this flag to specify that you do not want an informational message box to be displayed each time a file is automatically converted to Micro Focus format.
Set this flag to prevent a search filter being added with an * in the HLQ.
Set this flag to prevent a DFCONV conversion being performed on VSAM files imported on the PC.
Member download threshold | Specifies the maximum number of data set members that can be expanded before Drag and Drop displays a warning message advising that the operation will take some time.
Scan imported members for copy statements | Set this flag if you want to have the file or member being dragged from the mainframe checked for copy type statements and allow an automatic import of the related copy files.
Copy Statement Scanner Parameters When the Scan imported members for copy statements checkbox is checked, the downloaded files are scanned according to the rules in this group. Each rule consists of a description, a regular expression and an enabled flag.

The description is a free format description and can include any descriptive text. This text appears as part of the title of the selection dialog of found copy members.

The regular expression is a UNIX style regular search expression. The most important part is the grouping place holder signified by the contents of the bracket pair. i.e. ([A-Z0-9]*). See Below for a general explanation of regular expressions.

Add Scan Rule adds a new scan rule to the scan list.

Delete Rule deletes the selected rule from the list.

Save Rules saves the rules.

Reset All Rules resets the entire rule list to Micro Focus Defaults.

The Scan Enabled checkbox enables or disables the selected scan rule.

Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Drag and Drop Utility - Regular Expression Overview

Regular expression matching allows you to test whether a string fits into a specific syntactic shape. You can also search a string for a substring that fits a pattern.

A regular expression describes a set of strings. The simplest case is one that describes a particular string; for example, the string 'foo' when regarded as a regular expression matches 'foo' and nothing else. Nontrivial regular expressions use certain special constructs so that they can match more than one string. For example, the regular expression 'foo\|bar' matches either the string 'foo' or the string 'bar'; the regular expression 'c[ad]*r' matches any of the strings 'cr', 'car', 'cdr', 'caar', 'cadddar' and all other such strings with any number of 'a's and 'd's.

The first step in matching a regular expression is to compile it. You must supply the pattern string and also a pattern buffer to hold the compiled result. That result contains the pattern in an internal format that is easier to use in matching.

Having compiled a pattern, you can match it against strings. You can match the compiled pattern any number of times against different strings.

Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Drag and Drop Utility - Syntax of Regular Expressions

Regular expressions have a syntax in which a few characters are special constructs and the rest are "ordinary". An ordinary character is a simple regular expression which matches that character and nothing else. The special characters are '\$', '^', '.', '*', '+', '?', '[', ']' and '\'. Any other character appearing in a regular expression is ordinary, unless a '\' precedes it.

For example, 'f' is not a special character, so it is ordinary, and therefore 'f' is a regular expression that matches the string 'f' and no other string. (It does *not* match the string 'ff'.) Likewise, 'o' is a regular expression that matches only 'o'.

Any two regular expressions A and B can be concatenated. The result is a regular expression which matches a string if A matches some amount of the beginning of that string and B matches the rest of the string.

As a simple example, we can concatenate the regular expressions 'f' and 'o' to get the regular expression 'fo', which matches only the string 'fo'. Still trivial.

The following are the characters and character sequences which have special meaning within regular expressions. Any character not mentioned here is not special; it stands for exactly itself for the purposes of searching and matching.

. A special character that matches anything except a newline. Using concatenation, we can make regular expressions like a.b which matches any three-character string which begins with a and ends with b.
* Not a construct by itself; it is a suffix, which means the preceding regular expression is to be repeated as many times as possible. Fotr example, In fo*, the * applies to the o, so fo* matches f followed by any number of o's.

The case of zero o's is allowed: fo* does match f.

* always applies to the smallest possible preceding expression. Thus, fo* has a repeating o, not a repeating fo.

The matcher processes a * construct by matching, immediately, as many repetitions as can be found. Then it continues with the rest of the pattern. If that fails, backtracking occurs, discarding some of the matches of the *'d construct in case that makes it possible to match the rest of the pattern. For example, matching c[ad]*ar against the string caddaar, the [ad]* first matches addaa, but this does not allow the next a in the pattern to match. So the last of the matches of [ad] is undone and the following a is tried again. Now it succeeds.

+ Like * except that at least one match for the preceding pattern is required for +. Thus, c[ad]+r does not match cr but does match anything else that c[ad]*r would match.
? Like * except that it allows either zero or one match for the preceding pattern. Thus, c[ad]?r matches cr or car or cdr, and nothing else.
[ Begins a "character set", which is terminated by a ]. In the simplest case, the characters between the two form the set. Thus, [ad] matches either a or d, and [ad]* matches any string of a's and d's (including the empty string), from which it follows that c[ad]*r matches car, etc.

Character ranges can also be included in a character set, by writing two characters with a - (hyphen) between them. Thus, [a-z] matches any lower-case letter. Ranges may be intermixed freely with individual characters, as in [a-z$%.], which matches any lower case letter or $, % or period.

Note that the usual special characters are not special any more inside a character set. A completely different set of special characters exists inside character sets: ], - and ^.

To include a ] in a character set, you must make it the first character. For example, [ ]a] matches ] or a. To include a -, you must use it in a context where it cannot possibly indicate a range: that is, as the first character, or immediately after a range.

[^ Begins a "complement character set", which matches any character except the ones specified. So, [^a-z0-9A-Z] matches all characters except letters and digits.
^ Not special in a character set unless it is the first character. The character following the ^ is treated as if it were first (it may be a - or a ]).

^ is a special character that matches the empty string -- but only if at the beginning of a line in the text being matched. Otherwise it fails to match anything. Thus, ^foo matches a foo which occurs at the beginning of a line.

$ Similar to ^ but matches only at the end of a line. Thus, xx*$ matches a string of one or more x's at the end of a line.
\ Has two functions: it quotes the above special characters (including \), and it introduces additional special constructs.

Because \ quotes special characters, \$ is a regular expression which matches only $, and \ [ is a regular expression which matches only [, and so on.

For the most part, \ followed by any character matches only that character. However, there are several exceptions: characters which, when preceded by \, are special constructs. Such characters are always ordinary when encountered on their own.

No new special characters will ever be defined. All extensions to the regular expression syntax are made by defining new two-character constructs that begin with \.

\| Specifies an alternative. Two regular expressions A and B with \| in between form an expression that matches anything that either A or B will match.

Thus, foo\|bar matches either foo or bar but no other string.

\| applies to the largest possible surrounding expressions. Only a surrounding \( ... \) grouping can limit the grouping power of \|.

Full backtracking capability exists when multiple \|'s are used.

\( ... \) A grouping construct .To mark a matched substring for future reference. In the Micro Focus implementation, there is only one grouping allowed. The contents of this grouping are treated as the found filename for transfer.

This last application is not a consequence of the idea of a parenthetical grouping; it is a separate feature which happens to be assigned as a second meaning to the same \( ... \) construct because there is no conflict in practice between the two meanings. Here is an explanation of this feature:

\n After the end of a \( ... \) construct, the matcher remembers the beginning and end of the text matched by that construct. Then, later on in the regular expression, you can use \ followed by n to mean "match the same text matched the n'th time by the \( ... \) construct." The \( ... \) constructs are numbered in order of commencement in the regular expression.

The strings matching the first nine \( ... \) constructs appearing in a regular expression are assigned numbers 1 through 9 in order of their beginnings. \1 through \9 may be used to refer to the text matched by the corresponding \( ... \) construct.

For example, \(.*\)\1 matches any string that is composed of two identical halves. The \(.*\) matches the first half, which may be anything, but the \1 that follows must match the same exact text.

\b | Matches the empty string, but only if it is at the beginning or end of a word. Thus, \bfoo\b matches any occurrence of foo as a separate word. \bball\(s\|\)\b matches ball or balls as a separate word.
\B | Matches the empty string, provided it is not at the beginning or end of a word.
\< Matches the empty string, but only if it is at the beginning of a word.
\> Matches the empty string, but only if it is at the end of a word.
\w | Matches any word-constituent character.
\W | Matches any character that is not a word-constituent.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints


Allocate a new partitioned or sequential dataset

Dataset name | Specify the dataset name to be created on the mainframe.
Quantity | Specify the number of either cylinders, tracks or blocks to be allocated.
Type | Select the type of dataset to be created.
Directory blocks | This field is present only for the allocation of partitioned datasets. It is to contain the number of directory blocks to be placed in the mainframe partitioned dataset.
Logical record length | Specify the logical record length of the dataset
Block size | (Optional) If specified, the dataset will be created with this block size, otherwise the mainframe operating system will select the appropriate block size to be used.
Volume | (Optional) If specified, the dataset will be created on this volume, otherwise the mainframe operating system will select the appropriate volume to be used.
SMS storage class | (Optional) If specified, the dataset will be created with this SMS storage class information.
SMS data class | (Optional) If specified, the dataset will be created with this SMS data class information.
Expiration date | (Optional) If specified, both the YYYY and DDD fields must be filled in, and must contain a valid 4 digit year and 3 digit day of year field.
Get DCB from existing dataset | Select this button if you wish to read the DCB information from a existing mainframe dataset, and populate some of the fields on this panel.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Enter the required information

Specify the fully qualified mainframe dataset name that is to be looked up, so that some of the DCB information can be used to populate the fields in the allocate new dataset request.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Enter the required VSAM profile information

Minimum record length | Specify the minimum record length to be associated with this workstation indexed file.
Maximum record length | Specify the maximum record length to be associated with this workstation indexed file.
Key position | The mainframe VSAM relative key position is displayed for indexed datasets.
Key length | The mainframe VSAM key length is displayed for indexed datasets.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility - Syntax of Regular Expressions
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints


Enter the required CCC/LCM profile information

System | Specify the LCM system to be used.
Config | Specify the LCM configuration to be used within this system
Lock member on download | If you wish to automatically have the member locked when downloaded, then select this option.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Enter the required CCC/LCM profile information

Type | Specify the LCM member type for this member.
Change name | Specify the change name to be associated with this update.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints


Configure Advanced Filter Database

The Advanced filter database contains filter rules that can be strung together during the option configuration process. These filters can include and exclude files during the transfer process.

The database is held in text format in file called monrule.ini .

Add | Click this button to add a new rule to the database
Remove | Select an item in the list box, and click this button to remove it from the database.
Configure | Select an item in the list box, and click this button to configure the rule.
OK | Click this button to store any modifications to the database
Cancel | Click this button to abandon any changes made to the database
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Advanced filter details.

The Advanced filter database contains filter rules that can be strung together during the option configuration process. These filters can include and exclude files during the transfer process.

The database is held in text format in file called monrule.ini.

Rule Name | The name that the rule will be known by. The only restriction on this field is that it cannot contain spaces.
Rule Description | Free format field containing a meaningful description of the rule. This description is displayed during the selection of rules during the oprions configuration process.
Rule | A free format field containing the rule expression. The rule itself is called a "regular expression". The syntax is simple, but the expressions can be very complex. There is a short description of the syntax below.There are numerous tutorials on the Internet. Using any Internet search engine, search for "regexp tutorials"
OK | Click this button to store any changes to the database
Cancel | Click this button to abandon any changes made to the database

Regular expressions have a syntax in which a few characters are special constructs and the rest are "ordinary". An ordinary character is a simple regular expression which matches that character and nothing else. The special characters are '\$', '^', '.', '*', '+', '?', '[', ']' and '\'. Any other character appearing in a regular expression is ordinary, unless preceded by '\'.

For example, 'f' is not a special character, so it is ordinary. Therefore it is a regular expression that matches the string 'f' and no other string. (It does not match the string 'ff'.) Likewise, 'o' is a regular expression that matches only 'o'.

Any two regular expressions A and B can be concatenated. The result is a regular expression which matches a string if A matches some amount of the beginning of that string and B matches the rest of the string.

As a simple example, we can concatenate the regular expressions 'f' and 'o' to get the regular expression 'fo', which matches only the string 'fo'.

The following are the characters and character sequences which have special meaning within regular expressions. Any character not mentioned here is not special; it stands for exactly itself for the purposes of searching and matching.

. A special character that matches anything except a newline. Using concatenation, we can make regular expressions like a.b which matches any three-character string which begins with a and ends with b.
* Not a construct by itself; it is a suffix, which means the preceding regular expression is to be repeated as many times as possible. Fotr example, In fo*, the * applies to the o, so fo* matches f followed by any number of o's.

The case of zero o's is allowed: fo* does match f.

* always applies to the smallest possible preceding expression. Thus, fo* has a repeating o, not a repeating fo.

The matcher processes a * construct by matching, immediately, as many repetitions as can be found. Then it continues with the rest of the pattern. If that fails, backtracking occurs, discarding some of the matches of the *'d construct in case that makes it possible to match the rest of the pattern. For example, matching c[ad]*ar against the string caddaar, the [ad]* first matches addaa, but this does not allow the next a in the pattern to match. So the last of the matches of [ad] is undone and the following a is tried again. Now it succeeds.

+ Like * except that at least one match for the preceding pattern is required for +. Thus, c[ad]+r does not match cr but does match anything else that c[ad]*r would match.
? Like * except that it allows either zero or one match for the preceding pattern. Thus, c[ad]?r matches cr or car or cdr, and nothing else.
[ Begins a "character set", which is terminated by a ]. In the simplest case, the characters between the two form the set. Thus, [ad] matches either a or d, and [ad]* matches any string of a's and d's (including the empty string), from which it follows that c[ad]*r matches car, etc.

Character ranges can also be included in a character set, by writing two characters with a - (hyphen) between them. Thus, [a-z] matches any lower-case letter. Ranges may be intermixed freely with individual characters, as in [a-z$%.], which matches any lower case letter or $, % or period.

Note that the usual special characters are not special any more inside a character set. A completely different set of special characters exists inside character sets: ], - and ^.

To include a ] in a character set, you must make it the first character. For example, [ ]a] matches ] or a. To include a -, you must use it in a context where it cannot possibly indicate a range: that is, as the first character, or immediately after a range.

[^ Begins a "complement character set", which matches any character except the ones specified. So, [^a-z0-9A-Z] matches all characters except letters and digits.
^ Not special in a character set unless it is the first character. The character following the ^ is treated as if it were first (it may be a - or a ]).

^ is a special character that matches the empty string -- but only if at the beginning of a line in the text being matched. Otherwise it fails to match anything. Thus, ^foo matches a foo which occurs at the beginning of a line.

$ Similar to ^ but matches only at the end of a line. Thus, xx*$ matches a string of one or more x's at the end of a line.
\ Has two functions: it quotes the above special characters (including \), and it introduces additional special constructs.

Because \ quotes special characters, \$ is a regular expression which matches only $, and \ [ is a regular expression which matches only [, and so on.

For the most part, \ followed by any character matches only that character. However, there are several exceptions: characters which, when preceded by \, are special constructs. Such characters are always ordinary when encountered on their own.

No new special characters will ever be defined. All extensions to the regular expression syntax are made by defining new two-character constructs that begin with \.

\| Specifies an alternative. Two regular expressions A and B with \| in between form an expression that matches anything that either A or B will match.

Thus, foo\|bar matches either foo or bar but no other string.

\| applies to the largest possible surrounding expressions. Only a surrounding \( ... \) grouping can limit the grouping power of \|.

Full backtracking capability exists when multiple \|'s are used.

\( ... \) A grouping construct .To mark a matched substring for future reference. In the Micro Focus implementation, there is only one grouping allowed. The contents of this grouping are treated as the found filename for transfer.

This last application is not a consequence of the idea of a parenthetical grouping; it is a separate feature which happens to be assigned as a second meaning to the same \( ... \) construct because there is no conflict in practice between the two meanings. Here is an explanation of this feature:

\n After the end of a \( ... \) construct, the matcher remembers the beginning and end of the text matched by that construct. Then, later on in the regular expression, you can use \ followed by n to mean "match the same text matched the n'th time by the \( ... \) construct." The \( ... \) constructs are numbered in order of commencement in the regular expression.

The strings matching the first nine \( ... \) constructs appearing in a regular expression are assigned numbers 1 through 9 in order of their beginnings. \1 through \9 may be used to refer to the text matched by the corresponding \( ... \) construct.

For example, \(.*\)\1 matches any string that is composed of two identical halves. The \(.*\) matches the first half, which may be anything, but the \1 that follows must match the same exact text.

\b | Matches the empty string, but only if it is at the beginning or end of a word. Thus, \bfoo\b matches any occurrence of foo as a separate word. \bball\(s\|\)\b matches ball or balls as a separate word.
\B | Matches the empty string, provided it is not at the beginning or end of a word.
\< Matches the empty string, but only if it is at the beginning of a word.
\> Matches the empty string, but only if it is at the end of a word.
\w | Matches any word-constituent character.
\W | Matches any character that is not a word-constituent.

Examples

  • ^NULLFILE - will match a file called NULLFILE and nothing else.
  • ^NUL[0-9][0-9].* will match files beginning with NUL, followed by two numerics in the range 0-9, followed by any number of characters.
  • .*3$ will match any file ending with the number 3
  • ^A.*[0-3][1-2]$ will match any file beginning with the letter A, followed by any number of characters, the last two must be numeric and in the range 0-3 for the second last digit, and 1-2 for the last digit.
  • ^(CON)|^(NUL)|^(COM[0-9])|^(LPT[1-9])|^(AUX)|^(CLOCK\$) will exclude invalid DOS file names. Notice how to include the $ character as part of the string by preceding it with a backslash. If a rule is created like this and put in as an exclude filter when building the synchronisation item it would exclude all the invalid DOS filenames listed in this expression.

    The above would also hold true for a file called CONTROL. To stop this put a $ metacharacter as follows : ^(CON)$ .... This would ensure that only CON would be recognised by the filter.

Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints


Specify the dataset type

Select the dataset type to be monitored Specify the type of the mainframe dataset that a relationship is to be build.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop


Specify the mainframe dataset name

Specify the dataset name to be monitored Enter the fully qualified mainframe dataset name to be monitored.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints


Specify the mainframe Librarian dataset name

Specify the Librarian dataset name to be monitored | Enter the fully qualified name of the mainframe Librarian dataset to be monitored.
Specify the optional type, with or without filter characters | If your installation has gone to the trouble of setting up valid Librarian types on the mainframe, then you can take advantage of this information in selecting specific member types for you monitor relationship. You may specify a specific type, or use filter characters to be creative about a collection of types to be monitored. The filter characters are embedded with any other characters for pattern matching of the Librarian type, similar to the usage of the wildcard characters on the workstation directory command. The filter characters are:
 | * | any character may follow
 | ? | any character in this position
 | + | the character in this position must be non-blank
 | - | the character in this position must be a blank
 | / | the character in this position must be numeric
 | \ | the character in this position must be non-numeric
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints


Specify the mainframe Panvalet dataset name

Specify the Panvalet dataset name to be monitored | Enter the fully qualified name of the mainframe Panvalet dataset to be monitored.
Specify the optional type, with or without filter characters | If your installation has gone to the trouble of setting up valid Panvalet types on the mainframe, then you can take advantage of this information in selecting specific member types for you monitor relationship. You may specify a specific type, or use filter characters to be creative about a collection of types to be monitored. The filter characters are embedded with any other characters for pattern matching of the Panvalet type, similar to the usage of the wildcard characters on the workstation directory command. The filter characters are:
 | * | any character may follow
 | ? | any character in this position
 | + | the character in this position must be non-blank
 | - | the character in this position must be a blank
 | / | the character in this position must be numeric
 | \ | the character in this position must be non-numeric
Panvalet Status Processing | The groups of radio buttons in this section enable you choose to process only those Panvalet members that have the specified attributes set. For example, if Enabled, Active and Both are selected, the Compare and Synchronize Monitor downloads all members with Enabled and Active statuses; Production and Test statuses are both acceptable for download because of the Both option.Selecting these radio buttons only has an effect if you have updated your Mainframe Access server with one of the following PTFs: 2002PTF1, 2001PTF5, or MFAPANEH.EXE. If you have not installed one of these PTFs, these radio buttons have no effect. Contact your Micro Focus Support representative if you are not sure which of these PTFs is appropriate for your copy of Mainframe Access.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints


Specify the mainframe Endevor environment

Specify the environment | Enter the Endevor environment to be monitored.
System | Enter the Endevor system to be monitored.
Subsystem | Enter the Endevor sub-system to be monitored.
Specify the type | Endevor the specific Endevor type to be monitored.
Specify the CCID | If your environment requires a change control ID to be provided, then enter it here.
Specify the comment | If your environment requires a comment to be provided, or if you desire one, then enter it here.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints


Specify the mainframe LCM/CCC dataset name

Specify the LCM dataset name to be monitored | Enter the fully qualified name of the mainframe LCM dataset to be monitored.
Specify the system | Specify the LCM system to be monitored.
Specify the configuration | Specify the LCM configuration that is related to the LCM system to be monitored.
Specify the type | Specify the LCM type to be monitored.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints


Specify the mainframe sequential dataset name

Specify the sequential dataset name to be monitored Enter the fully qualified name of the mainframe QSAM dataset to be monitored.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints


Specify the mainframe VSAM dataset name

Specify the VSAM dataset name to be monitored | Enter the fully qualified name of the mainframe VSAM dataset to be monitored.
Handle as a fixed length file | The resulting imported file will be converted to the proper Micro Focus format in fixed format, with the minimum record length set to the maximum record length.
Parent topic: Using Enterprise Server with a Mainframe
Related concepts
Drag and Drop
Related information
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints